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Preface 


About this manual 


This manual documents MacApp™, the Expandable Macintosh Application. It contains 
reference information as well as detailed directions for the use of MacApp and all its parts. 


MacApp is a set of object-oriented libraries that implement the standard user interface for 
the Apple® Macintosh in such a way that application programs can be written as extensions — 
to MacApp. MacApp is intended to greatly speed development of application programs that 
work efficiently and conform to the standard Macintosh user interface. 


This manual assumes that you are a Pascal programmer and that you are familiar with the 
Macintosh. It assumes that you have studied the User Interface, QuickDraw, and File 
Manager chapters of Inside Macintosh (see “Other books you should have,” below), 
understand the concepts in the Resource Manager and Dialog Manager chapters of /nside 
Macintosh, and know how to use the Macintosh Programmer’s Workshop (MPW). 


This manual does not assume that you have written application programs for the 
Macintosh, although such experience would be helpful. This manual also does not assume 
that you know anything about object-oriented programming, although such knowledge 
would also be heipful. 


What this manual contains 
This manual has ten chapters and two appendixes: 


Chapter 1, “Introduction to Object-Oriented Programming.” This chapter is an introduction 

_to programming in Object Pascal intended for people who are not familiar with this 
programming style. A more thorough introduction to this technique, such as Object- 
Oriented Programming for the Macintosh, by Kurt J. Schmucker (Hayden, 1986), might 
also be helpful. 


Chapter 2, “How MacApp Works.” This chapter describes how MacApp is structured and 
how its parts fit together. It is a largely theoretical introduction to MacApp, but also 
provides a framework for understanding the more specific information in the rest of the 
manual: f . 


Chapter 3, “Using MacApp.” This chapter describes the MacApp package, how to install 
MacApp on your disk, and how to build a MacApp program. It also describes the sample 
programs provided with MacApp and has an index to features demonstrated in the sample 


programs. 


Chapter 4, “Drawing.” This chapter is an overview of how drawing occurs in MacApp 
programs. 


Chapter 5, “The Cookbook.” This chapter gives detailed directions for writing simple and 
complex MacApp programs. It has recipes for the use of all of the features of MacApp, for 
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_ overriding features of MacApp, and for implementing features that are not included in 
MacApp. 


Chapter 6, “Object-Oriented Assembly Language.” This chapter describes a set of MPW 
Assembler macros that allow you to write part or all of your MacApp program in assembly 
language. 


Chapter 7, “The Flow of Control in Response to Events.” This chapter shows the 
sequences of calls in MacApp programs in response to certain events. 


Chapter 8, “The MacApp Debugging Facilities.” This chapter documents the use of the 
MacApp debugging facilities: the Debug window, the Debug menu, and the Interactive 
Debugger. 


Chapter 9, “Globals.” This chapter provides reference documentation for the global 
constants, types (other than object types), variables, procedures, and functions included in 
the MacApp package. 


Chapter 10, “Object and Method Reference.” This chapter documents the object types 
defined in the MacApp package, outlining the fields and methods of each object type. 


Chapter 11, “Debugging Reference.” This chapter documents the globals, object-type 
fields, and methods that are present when MacApp is compiled with debugging on. 


Appendix, “Routine Name Index.” This index lists all methods and global routines by 
name. If you only know the name of a routine, and not what its defining object is or 
whether it is a global routine, look in this list. 


How to use this manual 


If you are new to object-oriented programming or to Object Pascal, begin with Chapters 1, 
2, 3, and 4. 


If you are familiar with object-oriented programming and Object Pascal, you can skip 
Chapter 1, but all readers should read Chapters 2, 3, and 4. (Reference documentation for 
the MPW implementation of Object Pascal is in the Macintosh Programmer's Workshop 
Pascal Reference .) 


Then, turn on your computer, move to Chapter 5, “The Cookbook,” and start 
programming. 


When you need to debug your program, turn to Chapter 8, “MacApp Debugging 
Facilities.” If you need more information about what is going on in your program, you 
may want to refer to Chapter 7, “The Flow of Control in Response to Events.” 


If you need more detail about the globals or the objects and methods defined in MacApp, 
go to Chapters 9, 10, and 11. You may need that information if you want to go beyond the 
basic features implemented in the recipes in Chapter 5. 


Finally, if you want to reimplement some of your application in assembly language, to 
make your code more efficient, look at Chapter 6, “Object-Oriented Assembly Langage.” 
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Notation 


In this manual and the MacApp code, identifiers follow a number of notational conventions 
designed to help you identify the use of each element: 


@ 


All variable and constant identifiers begin with a lowercase letter. 
Global variable identifiers begin with a g (for example, gTarger). 
Command constants begin with a c (for example, cNew). 


Most other constants (except command constants) begin with a k (for example, 
kStdScroll). È 


Field identifiers of object types (see Chapter 1) begin with an f (for example, 
JDocumeni). ` : 


Routine names and type names begin with an uppercase letter (for example, Enable). 
Object type identifiers (see Chapter 1) begin with a T (for example, TWindow). 
_ Compiler variables begin with a q (for example, qDebug). 


Words embedded within variable identifiers and routine names begin with an 
uppercase letter (for example, ForAllWindowsDo). : 


These additional notation conventions are used in this manual: 


Identifiers or parts of identifiers you are expected to replace include the word Your 
(for example, TYourDocument). 


© Generic references to objects of a given object type are named with the type name 


without the T (for example, an object of type TWindow is called window). 


e Pascal reserved words and predefined type names are printed entirely in uppercase 


letters (for example, INTEGER). 


> The routines contained in the Macintosh ROM as well as a number of software 


packages that are similarly central to the Macintosh system are referred to as /nside 
Macintosh routines. All such routines are documented in /nside Macintosh. 


MacApp and Object Pascal do not add any special checking to enforce these conventions. 
As usual in Pascal, uppercase and lowercase letters are equivalent in Object Pascal 
programs. 


A 


Important; Uppercase and lowercase characters are equivalent in Pascal identifiers 
because all characters in Pascal identifiers are converted to uppercase. When using 
MPW Assembler, all identifiers are generally converted to uppercase as with Pascal 
programs. You can use an Assembler directive to make case significant, but that is not 
recommended when using the Assembler with MacApp. 


word about development systems 


This manual is written for use with the the Macintosh Programmer’s Workshop (MPW). If 
you are using a different development system but still working with Object Pascal, most of 


this 


will apply. If you are using a language other than Object Pascal, check the 


documentation for that language and adapt what is here. 
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System requirements | 


MacApp can be used to program on any Macintosh with a hard disk and at least one 
megabyte of memory. It can be used on a Macintosh, Macintosh Plus, and Macintosh XL 
computers. It can be used with the original 64K ROMs and the new 128K ROMs. Both 
the non-hierarchical file system (the Macintosh File System, or MFS) and the hierarchical 
file system (HFS) are supported. 


In order to print on the LaserWriter, you must have LaserWriter driver version 3.0 or later. 


Programs produced with MacApp can run on any Macintosh, within the limits of the 
memory requirements of the final program. 


For more information on compatibility with System File, Finder, and LaserWriter software 
versions, contact Apple Developer Technical Support. 


Other books you should have 


You will need the following books to accompany this manual: 


°. Inside Macintosh, Volumes I and II (Addison-Wesley, 1985) and Volume IV 
(Addison-Wesley, 1986). (You do not need volume III, but you may find it useful.) 
This is the essential reference for writing Macintosh applications. It documents the 
Macintosh ROM routines and other routines basic to the operation of the Macintosh. 
Although MacApp saves you from needing to know everything in Inside Macintosh, 
you sull need to be familiar with the User Interface, QuickDraw, and File Manager 
chapters, and you may need to be familiar with the Window Manager, Resource 
Manager, Menu Manager, Dialog Manager, and Control Manager chapters. (You 
probably won’t need to use routines documented in other parts of Inside Macintosh, 
but you can use any routines you wish in MacApp applications.) 


e Macintosh Programmer's Workshop Pascal Reference (Apple Computer, 1986). 
This documents Apple’s version of the Object Pascal language. If you are using a 
different version of Object Pascal or a different set of object-oriented extensions that 
you know work with MacApp, you may not need this book. 


e Macintosh Programmer's Workshop Reference (Apple Computer, 1986). This 
documents the MPW development system. If you are using a different development 
system, you do not need this manual. 


e If you intend to write Object Assembler programs, you need the Macintosh 
Programmer's Workshop Assembler Reference (Apple Computer, 1986). 


In addition, technical notes and other material of interest to Macintosh application 
developers are available from the Apple Programmer's and Developer's Association. 
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Chapter 1 


Introduction to Object-Oriented 
Programming 


Although MacApp makes creating Macintosh applications much easier, it requires a Style of 
programming, called object-oriented programming, that you might not be familiar 
with. This chapter provides a short introduction to object-oriented programming, with a 
discussion of object-oriented programming in general followed by a discussion of Object 
Pascal (the language used to implement MacApp). 


This chapter and most of the rest of this manual assumes you will program your application 
in Object Pascal, which is included in MPW Pascal. You can also use MacApp with MPW 
Assembler and a number of other languages. Object-oriented assembly language is 
discussed in Chapter 6 of this manual. 


‘Object-oriented programming 


Object-oriented programming is essentially a style of programming that uses some new 
constructs and concepts to change the way programs are written. Object-oriented programs 
may or may not use MacApp, so much of this chapter discusses the fundamental concepts 
of this programming style without reference to MacApp. However, MacApp applications 
must be written as object-oriented programs, so you need to understand this programming 
style before you can use MacApp. 


How is object-oriented programming different? 


Most programs are procedure-oriented. That means they are organized around 
procedures and functions. In a procedure-oriented program, you decide what tasks need to 
be performed and write procedures and functions to carry out the tasks. The data on which - 
the procedures and functions operate is stored in variables of different kinds, including 
structured variables such as arrays and records. 


MacApp programs are object-oriented. An object-oriented program is organized around 
objects. Objects are places for data storage, much like Paseal records, but they also have 
‘methods, which are routines that operate on the object’s data. The essential point is that 
you decide on your data structures first, and then decide what routines you need to operate 
on the data structures. You can do that in any language; in an object-oriented language, 
however, you can group the data structures and the routines together into objects. 


If procedures and functions are verbs and pieces of data are nouns, a procedure-oriented 
program is organized around verbs while an object-oriented program is organized around 
nouns. Imagine that you had a program that operated dogs, mice, and cats, Further, 
imagine that the program needed to implement eating and running for the dogs, mice, and 
cats. To write this in a verb-oriented (procedure-oriented) way, you would write 


dog = RECORD 
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mouse = RECORD 
cat = RECORD 


PROCEDURE Eat {animal) 
IF animal = dog THEN eat this way 
IF animal = mouse THEN eat another way 
IF animal = cat THEN eat a third way 
END 


PROCEDURE Run (animal) 
IF animal = dog THEN run this way 
IF animal = mouse THEN run another way 
IF animal = cat THEN run a third way’ 
END 


To write this program in a noun-oriented (object-oriented) way, you would write 


deg = OBJECT 
PROCEDURE Eat 
PROCEDURE Run 
END 


mouse = OBJECT 
PROCEDURE Eat 
PROCEDURE Run 
END 


cat = OBJECT 
PROCEDURE Eat 
PROCEDURE Run 
END 


This is not intended to demonstrate any advantages of object-oriented programming, just to 
illustrate the organizational difference. 


What are objects? 


Suppose you write a Pascal program that draws an oval, such as the following: 


PROGRAM Oval; 
VAR - boundRect: Rect; {bounding box} 
pattern: Pat; ; 


PROCEDURE IOval(left, top, right, bottom: INTEGER); {Initialize oval} 
BEGIN 

SetRect (boundRect, left, top, right, bottom);. 

pattern := black; 
END; 


PROCEDURE Draw; 
BEGIN 

FillOval(boundRect, pattern); 
END; 


BEGIN 
TOval(10, 50, 200, 300); 
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Draw; 
END. 


Suppose, further, you want to create a program that draws boxes. 


PROGRAM Box; 
VAR boundRect: Rect; {bounding box} 
pattern: Pat; 


PROCEDURE IBox(left, top, right, bottom: INTEGER); {Initialize box} 
BEGIN : 

SetRect (boundRect, left, top, right, bottom); 

pattern := black; i 
END; 


PROCEDURE Draw; 
BEGIN 

FillRect (boundRect, pattern); 
END; 


BEGIN 
IBox(10, 50, 200, 300); 
Draw; 

END. 


These little programs are actually something like objects: they contain data, and they have 
procedures that operate on the data. The procedures in each program can operate only on 
the data in that program. Also, each program “knows” how to do its task: Oval can draw 
ovals; Box can draw boxes. 


An object is like a little program, a “machine” that does its task in an independent manner. 
Here are object-type declarations for the object types TOval and TBox. (By convention, all 
object-type identifiers in MacApp begin with a7.) Notice that, although the syntax is a bit 
different, they are organized like programs. 


TOval = OBJECT 
boundRect: Rect; {bounding box} 
pattern: Pat; 
PROCEDURE TOval.IOval(left, top, right, bottom: INTEGER); {Initialize 
oval} 
PROCEDURE TOval.Draw; 
END; 


TBox = OBJECT 
boundRect: Rect; {bounding box} 
pattern: Pat; 
PROCEDURE TBox.IBox(left, top, right, bottom: INTEGER); {Initialize 
box} i 
PROCEDURE TBox.Draw; 
END; 


The fields of these objects, boundRect and pattern, are declared like the fields of records. 
In fact, you refer to the fields of an object in the same way you refer to the fields of a 
record. For example, if you declare a variable of type TOval: 


anOQval: TOval. 
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you can refer to the fields of the object like this: 


anOval.boundRect 
anOval.pattern 


As you can see from the declarations of TOval and TBox, when you define an object type, 
you just define the interface to the procedures and functions of the object. These “private” 
procedures and functions are called methods of the object. You define the implementation 
of the methods later. This is equivalent to a FORWARD declaration, in that you can have 
forward references within the blocks of the routines. The implementation of these routines 
would look much like they did before. Here is one: 


PROCEDURE TBox.Draw; 
BEGIN 

FillRect (boundRect, pattern); 
END; 


Just as you can refer to the global variables boundRect and pattern anywhere in the 
program Box, you can refer to the fields boundRect and pattern anywhere “within” an 
object of type TBox without qualifying those fields. 

To invoke a method of an object, you refer to it in the same way you refer to a field. When 
you are “outside” the object anOval (in the main program or in a method of another object), 
you write: 


anOval.Draw 


However, if you want to call TOval.Draw from within a method of the same object type, 
you just use the identifier Draw. You might write another method for TOval as follows: 


PROCEDURE TOval.Flash; 


BEGIN 
pattern := white; 
Draw; 
pattern := black; 
Draw; 

END; 


Each call to Draw always calls TOval.Draw. In a sense, every field and method of an 
object type is within the scope of the object type. 


An object-type declaration is a template that defines the characteristics and capabilities 
(fields and methods) of objects of that type. Fields and methods are very much alike, 
except that each object can have different values in its fields, but every object of a given 
object type has the same methods. Going back to the dog, cat, and mouse example, each 
cat may differ from other cats in weight or color, but every cat eats and runs in the same 
way. The methods determine the characteristics of the species; thé fields determine the 
characteristics of the individual within the limits of the species. 


Inheritance 
Just as species can have ancestor species from which they inherit characteristics, object 


types can have ancestor object types from which they inherit characteristics. As with 
species, the descendant type can change characeristics inherited from its ancestor. Among 
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animals, dogs and bears are descended from a common ancestor. They both acquired the 
ability to walk on four legs; one or both of them changed the way that ability is 
implemented. Similarly, descendant object types inherit capabilities, and they may 
reimplement some of them. 


Notice that the declarations of TOval and TBox are very similar. Suppose we define a new 
object type, TShape: 


TShape = OBJECT 
boundRect: Rect; {bounding box} 
pattern: Pat; i 
PROCEDURE TShape.IShape(left, top, right, bottom: INTEGER) ; 
{Initialize shape} f 
PROCEDURE TShape.Draw; 
END; 


This is an abstract object type. An abstract object type is one you don’t expect to use to 
create an object; it exists to provide a framework for its descendants. TShape is abstract 
because its Draw method can’t really do anything: you can’t draw a shape in a general way; 
you can only draw specific types of shapes like ovals and boxes. 


Once we’ve defined TShape, we can change the declarations of TOval and TBox: 


TOval = OBJECT (TShape) 
. PROCEDURE TOval.IOval(left, top, right, bottom: INTEGER); {Initialize 
oval} 
PROCEDURE TOval.Draw; OVERRIDE; 
END; 


TBox = OBJECT (TShape) 
PROCEDURE TBox.IBox(left, top, right, bottom: INTEGER); {Initialize 
box} 
PROCEDURE TBox.Draw; OVERRIDE; 
END; 


When the reserved word OBJECT is followed by an object-type identifier in parentheses, 
the new object type is a customization of the old one. That means the new type acquires 
all the fields and methods of the old-type. OVERRIDE is-a required reserved word 
meaning that a method is inherited but its implementation will be changed. 


In these definitions, notice that the fields are not declared for TOval and TBox. They are 
inherited from TShape. Similarly, IShape is inherited, and can be called from IOvai and 
[Box in the same way any method of TOval or TBox is called. 


One advantage of inheritance is that you can declare a variable of the ancestor type: 
aShape: TShape 


An object-type variable (called an object-reference variable) is a kind of pointer type 
variable that holds a reference to an object. Objects are created like identified variables (the 
referents of pointers), and, like identified variables, exist independently of the references to 
them. It doesn’t make sense to create an object using TShape, because it couldn’t actually 
draw itself, but you could create an object of type TOval or TBox and assign the reference 
to aShape. (As with all pointers, the type of the identified variable must be compatible, but 
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descendant types are compatible with variables of ancestor types.) Then, you can have a 
statement like 


aShape .Draw 


This statement calls the Draw method for the kind of object whose reference is stored in 
aShape, even though, when you wrote the statement, you may not have known what kind 
of object would be there at execution. This “very late binding” capability is the key feature 
of object-oriented programming. 


Comparing a procedure-oriented program and an object-oriented 
program 


As mentioned before, the difference between a procedure-oriented program and an object- 
oriented program is a matter of style. You can use either approach to do the same thing. 
Each approach has advantages in certain areas. l 


Object Pascal adds object-oriented structures to Pascal and is included in MPW Pascal. 
Pascal programmers should have little difficulty adjusting to Object Pascal, because most of 
what they know about Pascal is true for Object Pascal. 


This chapter gives two MPW Pascal example programs: a procedure-oriented program, 
PasExample, and an object-oriented program, ObjExample. Both are listed under 
“Programs” at the end of this chapter. The examples in the remainder of this chapter are 
from these programs. 


The object-oriented program and the procedure-oriented program, when run, do the same ` 
things. When either is run in the Macintosh Programmer’s Workshop, it prints a command 
line in a window. The user, using the command line, chooses to draw and move arcs or 
rounded-comer rectangles. Only one shape appears on the screen at a time; when a shape 
is drawn or moved the old shape is erased. 


The difference between the programs is that the object-oriented program, because of the 
structure of Object Pascal, can be easily extended to have new types, while the procedure- 
oriented program cannot. The examples show the difference between the procedure- 
oriented structure of ordinary Pascal programs and the object-oriented structure of Object 
Pascal programs. 


The procedure-oriented program, PasExample 
PasExample, the Pascal program, is written in MPW Pascal without the use of objects, 
In PasExample, arcs and rounded-comer rectangles are defined in a record-type definition: 
AShape = RECORD 
boundRect: Rect; 
CASE kind: EShape OF 
kArc: (startAngle, arcAngle: INTEGER); 


kRoundRect: (ovalWidth, ovalHeight: INTEGER); 
END; i 
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This example is the record definition of AShape. Thus, both arcs and rounded-corner 
rectangles have a boundRect field. Note that a variant record part is used to add startAngle 
and arcAngle to the kArc variant of AShape and ovalWidth and ovalHeight to the 
kRoundRect variant. Figure 1-1 illustrates the fields of an arc and a rounded-comer 
rectangle. 


Figure 1-1 
Data Fields in kAre and kRoundRect 


kRoundRect 


fBoundRect 


fOvalWidth 


©] fOvalHeight 


Aside from storage allocation procedures, PasExample defines six procedures and 
functions. The Run procedure controls the execution of the program. The other five 
procedures and functions act on arcs and rounded-corner rectangles. The NewArc function 
creates an arc and the NewRoundRect function creates a rounded-comer rectangle. The 
DrawShape procedure draws an arc or a rounded-corner rectangle, and the EraseShape 
procedure erases an arc or a rounded-cormer rectangle. The RandomRect procedure assigns 
the rectangle within which the arc or rounded-comer rectangle is drawn. 





[are] 
fBoundRect |: 
fStartAngie 


fArcAngle 



















Note these elements in PasExample that are typical of a Pascal program that is written 
without using objects: 


e PasExample was implemented using handles—double-indirect pointers (^^) to 
records—and a heap on which the records are stored. The type TShape is a handle to 
an AShape-type record. 


e Within Pascal programs, information is grouped by operations (procedures and 
functions). This grouping by operations scatters information about each type of data 
structure within the program. For example, if you want to see what.can be done with 
arcs in PasExample, you have to look at NewArc, DrawShape, EraseShape, and 
RandomRect. 


e In PasExample, there is one drawing procedure for all shapes. 


PROCEDURE DrawShape (pat: Pattern; SELF: TShape); 
BEGIN 
CASE SELF**.kind OF 
kArc: 
BEGIN : 
FillArc(SELF**.boundRect, SELF**.startAngle, 
SELF**.arcAngle, pat); 
FrameArc (SELF** .boundRect, SELF**.startAngle, 
SELF**.arcAngle) ; 
END; 
kRoundRect: 
BEGIN 
FillRoundRect (SELF**.boundRect, SELF**.ovalWidth, 
SELF** .ovalHeight, pat); 
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FrameRoundRect (SELF**..boundRect, SELF**.ovalWidth, 
SELF** .ovalHeight) ; 
END; 
END; 
END; 


e The CASE statement determines how to draw a particular shape. 


e In PasExample, as in all Pascal programs, it would be easy to add a new 
operation because it is a procedure-oriented language and information is 
grouped by operation. It would, however, be difficult to add another variant 
of AShape. To do so, you would have to edit the declaration of the AShape 
record, and add to the CASE statements in all procedures and functions in the 
program. If the source code is unavailable, or.if the object code is from a 
shared library, it is impossible to add another variant. 


The object-oriented example, ObjExample 


ObjExample, the Object Pascal program, is written in MPW Pascal using objects. This 
means that ObjExample is organized around objects (nouns), not procedures and functions 
(verbs) like PasExample. This section briefly covers ObjExample—more details on Object 
Pascal are in the following sections. 


When ObjExample is run, it prints a command line on the top of the screen. The user, 
using the command line, chooses to draw and move arcs or rounded-corner rectangles. 
Only one shape appears on the screen at a time; when a shape is drawn or moved the old 
shape is erased. 


In ObjExample, arcs and rounded-corner rectangles are defined in object-type definitions. 
First, the most general object type, TShape, is defined, and then TArc and TRoundRect are 
defined: 


TShape = OBJECT (TObject) 
fboundRect: Rect; {bounding box} 
PROCEDURE TShape.IShape; {Initialize fields} 
. PROCEDURE TShape.RandomRect; (Assign a random rectangle to boundRect! 
PROCEDURE TShape.Move; {Assign a different random rectangle to 
boundRect } 
PROCEDURE TShape.Draw({pat: Pattern); 
PROCEDURE TShape.Erase; 
END; i 


TArc = OBJECT (TShape) 
fStartAngle, fArcAngle: INTEGER; 
PROCEDURE TArc.IArc; {Initialize fields} 
PROCEDURE TArc.Draw(pat: Pattern); OVERRIDE; 
PROCEDURE TArc.Erase; OVERRIDE; 
END; 


TRoundRect = OBJECT (TShape) 
fOvalWidth, fOvalHeight: INTEGER; {curvature of rounded corners} 
PROCEDURE TRoundRect.IRoundRect; {Initialize fields} 
PROCEDURE TRoundRect.Draw(pat: Pattern); OVERRIDE; 
PROCEDURE TRoundRect.Erase; OVERRIDE; 
END; 
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Note that there are three Draw methods, three Erase methods, and one Move method. This 
is because TArc and TRoundRect inherit the Move method, and OVERRIDE (reimplement) 
the Draw and Erase methods. 


These concepts and ObjExample are discussed in more detail throughout this chapter. 


An introduction to Object Pascal 


This section discusses the language used to implement MacApp, Object Pascal. Most of 
the concepts discussed here were introduced in the “Object-oriented programming” and 
“Comparing a procedure-oriented program and an object-oriented program” section of this 
chapter, but are reintroduced here in the context of Object Pascal’s syntax and terminology. 


Object Pascal programs are structured around object types. Just as any variable is 

- defined by its type, an object is defined by its object type. Unlike other kinds of types, the 
object type defines both the type of data structure the object has and the operations 
(procedures and functions) that the object can perform. 


Object types belong to an object hierarchy. This hierarchy makes it possible for object 
types to share characteristics belonging to object types above them in the object-type 


hierarchy. Figure 1-2 illustrates the basic Object Pascal hierarchy and introduces some 
fundamental Object Pascal terms. 


Figure 1-2 
Object-type hierarchy 






ancestors of 


immediate ancestor of X 
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Every circle in Figure 1-2 is an object type. Within the hierarchy, object types have 
relationships. Ancestor object types are object types that are above an object type in 
hierarchy——-A and B are X’s ancestors. Descendant object types are object types that 
are below an object type in the hierarchy—C, D, E, F, and G are descendents of X. An 
immediate descendant is an object type that is one level below another in the 
hierarchy—C,D, and E are immediate descendants of X. The process of declaring an 
immediate descendant is called customizing the ancestor object type. An immediate 
ancestor is an object type that is one level above an object type in the hierarchy—B is X’s 
immediate ancestor. These concepts are discussed in more detail later in this chapter. 


Note: Other texts use a different set of terminology in describing Object Pascal, derived 
from the terminology used for Smalltalk. A class is equivalent to an object type. A 
subclass is equivalent to an immediate descendant. “To subclass” is equivalent to “to 
customize.” A superclass is equivalent to an immediate ancestor. Finally, a 
message is equivalent to a method call. 


One object type, TObject, is necessary for writing Object Pascal programs. TObject 
defines the most general characteristics of all Object Pascal objects. For example, TObject 
provides a general method for copying an object and a method for discarding an object. 
Additional object types in a program are defined by the programmer. 


Important: Most Object Pascal programs are written to use MacApp. MacApp is made 
up of a set of units that define a number of object types descended from TObject. 
Programs using MacApp define their own object types as descendants of TObject and 
of the object types defined in the MacApp units. You can write Object Pascal programs 
without MacApp. If you want to do that, have Objinf in the USES part of your 
application and link with ObjLib.o. 


TObject is the ultimate ancestor object type of all object types in the Object Pascal 
hierarchy. 


Note: You don’t have to use TObject as the ultimate ancestor of your object types, but 
it is recommended that you do so because it provides facilities needed by all objects. 


A new object type is created by declaring it as a customization of another object type. This 
establishes a place for the new object type in the hierarchy. The new descendant inherits 
the characteristics of its ancestors and new characteristics can be added. 


An object of any object type is an instance of its own object type and a member of all its 
ancestor object types. All objects are members of the object type TObject, as well as 
members of their own object types. The process of creating an instance of an object type is 
often called instantiating the object type. 


The sample Object Pascal program, ObjExample, has two descendants of TObject: TShape 


and TControl. TShape has two descendants: TArc and TRoundRect. Figure 1-3 shows 
the object-type hierarchy in ObjExample. 
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Figure 1-3 
Hierarchy of Object Types in ObjExample 





The identifiers or types for inherited data fields cannot be changed in a descendant, 
although fields can be added. Similarly, the interface for a method cannot be changed, but 
inherited methods can be reimplemented. Reimplementing a method is called 
overriding a method. 


For example, consider ObjExample, which draws and moves arcs and rounded-corner 
rectangles. TShape defines the most general characteristics of shapes. These 
characteristics are a data field, boundRect, and five methods: 


e [Shape (initializes an object of type TShape) 

e Draw ( draws an object of type TShape ) 

e Erase (erases an object of type TShape) 

e Move (moves an object of type TShape) 

e RandomRect (assigns a random size to an object of type TShape) 


Note that TArc and TRoundRect inherit the definition of fBoundRect from TShape, but that 
each member of the object type has its own fBoundRect field. TArc adds two additional 
data fields, fStartAngle and fArcAngle, overrides Draw and Erase, and adds its own 
initialization method. Similarly, TRoundRect adds two additional data fields (fOvalWidth 
and fOvalHeight), overrides Draw and Erase, and adds its own initialization method. 
Because drawing and erasing is different for arcs and rounded-corner rectangles, TArc and 
TRoundRect define their own Draw and Erase methods. Initializing fBoundRect is the 
same for all shapes, so RandomRect is inherited by both TArc and TRoundRect 
unchanged. Figure 1-4 illustrates this example. 
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Figure 1-4 
Inheritance in ObjExample 


[ TShape 


. TRoundReci 
[ancang _| 
[ feouncRect | 





In Object Pascal, all object information is centralized within an object-type definition and 
implementation. An operation definition within an Object Pascal program, because it is 
organized within object types, is distributed throughout the program. For example, if you 
want to see how drawing is accomplished in ObjExample, you have to look in the method 
implementations for TShape, TRoundRect, and TArc. In PasExample, you had to look 
only in the one DrawShape procedure. 


Later in this chapter you will see how the object-type structure allows easy extension of 
Object Pascal programs and how this ability is used by MacApp. 
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As explained above, an object is an instance of an object type, just as a record variable is 
an instance of a RECORD type. An object is not the same as an object type. An object 
type defines the fields and methods that an object of its type will have, but is not one of the 
objects it defines; just as a Pascal RECORD type defines a record, but it is not one of the 
records it defines. 


An object-reference variable is a special pointer-type variable that is used to refer to an 
object. The type of an object-reference variable is always an object type. You can only 
assign a reference to an object or NIL to an object-reference variable. In ObjExample the 
lines 

gControl: TControl 

thisShape: TShape 


are object-reference variable declarations: gControl is of object type TControl and 
thisShape is of object-type TShape. 


When you refer to an object’s field or method with an object-reference variable, the handle 
is automatically dereferenced. This is very different from Pascal. Assume that, in a Pascal 
program, anArcHandle refers to an identified variable that has an arcAngle field. To refer 
to the arcAngle field, you would have to explicitly write - 
anArcHandle**.arcAngle 


In Object Pascal, the double indirection is taken care of automatically. To refer to the same 
field in an arc object referred to by anArcObj, you would write 


anArcObj.arcAngle 

Master pointers are maintained by the Memory Manager. When the space on the heap is 
relocated to make room for other objects, the Memory Manager changes the master pointer. 
Because the application uses the handle (which points to the master pointer), the application 
does not need to know about the change in the heap because the location of the master 
pointer never changes. 

To refer to a data field in an object, the format is objectReference.fieldName. 


Note that carets (^^) are never used to resolve an object reference—the double indirection is 
implicit. 


Figure 1-5 shows how object references in ObjExample are handles on objects in the heap. 
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Figure 1-5 
Object references in ObjExample 










_ Fragment of ObjExample | 


TRoundRect = OBJECT (TShape) 
fOvalWidth, fOvalHeight: INTEGER; _ 





PROCEDURE TRoundRect.IRoundRect; 

BEGIN 
TShape; 
fOvalWidth:= 207 
fOvalHeight:= 15; 












af master } 
“4 pointer J 
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Note in Figure 1-5 that aRoundRect is the object reference, that fOvalWidth is the field 
name, and that aRoundRect.fOvalWidth is a field designator that refers to the object’s 
fOvalWidth field. 


An object can have more than one reference, but each object has only one master pointer. 
The master pointer is the direct link to objects on the heap. More than one object-reference 
variable can contain identical handles; they would all point to the same master pointer. 
Assigning the same handle to another object-reference variable creates a new path to the 
same object. Figure 1-6 illustrates the assignment of one object-reference variable to 
another. 
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Figure 1-6 
A new path to the same object 


z Fragment of ObjExample § 


PROCEDURE TControl.Run; 
VAR thisShape: TShape; 
nextShape: TShape; 


















thisShape:= next Shape 





xD 


Note that thisShape and nextShape are object-reference variables of type TShape, and so 
can refer to any object of types TShape, TArc, or TRoundRect, or any other descendant of 
TShape, even one that is defined after this unit is compiled. 

Methods 


As explained above, an object-type declaration defines all the methods that an object of that 
type can perform. All objects of the same object type use the same methods. 


The methods associated with an object make it possible for an object to act on its own data. 
A method call tells an object to execute one of its methods. Whenever an object executes a 
method, the method acts on the data that the object stores. . 

All objects of the same object type respond to the same method calls. The format of a 
method call is objectReference.Method(arguments). Method(arguments) has the same 
syntax as a Pascal procedure or a function call. In ObjExample, for instance, 


PROGRAM MObjExample; 
VAR 


gControl: TControl; 
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BEGIN 


gControl.Run; 


gControl.Run is a method call with no arguments. gControl is an object-reference variable 
of type TControl. The method call gControl.Run tells the object referred to by gControl to 
execute its Run method. Figure 1-7 illustrates these steps. 


Figure 1-7 
Method Call to an Object ` 


— | Fragment of ObjExample 












gControl: TControl; 


gcontrol.Run 
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Object types and methods, combined with object references, allow you to write code with 
method calls without knowing what object will be referred to at run time. This is beneficial 
because it increases the extendability of Object Pascal code. (Code extensibility is 
discussed under “Extending an Object Pascal program,” later in this chapter.) For 
‘example, in the statement 


thisShape.Draw(gray); 
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(from ObjExample) the value of thisShape is not determined until run time. TArc and 
TRoundRect each have a Draw method. At mun time, the correct Draw method is executed. 


You can consider that a method table is set up for each object type by the Object Pascal 
compiler. The method table for a particular object type contains pointers to the methods 
that the objects of that type use and all objects of that type share the method table, Figure 
1-8 illustrates this. Notice that the method table includes methods defined specifically for 
the object type as well as methods inherited from the ancestor. (A compressed form of 
method table is actually used in the current version of MPW Pascal, but the concept 
illustrates how methods relate to object types.) 


Figure 1-8 
A method table 
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Note: You may have noticed that the syntax for a reference to a data field and the 
syntax for a method call is identical. The syntax is 





























* -objectReference.fieldName for a reference to a data field 

* objectReference.Method for a method call 
To help readers tell them apart, in this manual field names begin with a lowercase f whereas 
method names begin with an uppercase letter. 
Object type hierarchy and inheritance 


The OVERRIDE qualifier must be used in the interface whenever an inherited method is . 
reimplemented. : 
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The type definitions for TShape, TArc, and TRoundRect are listed below; note the use of 
OVERRIDE. 


TShape = OBJECT (TObject) 
fBoundRect: Rect; {bounding box} 
PROCEDURE TShape.IShape; {Initialize fields} 
PROCEDURE TShape.Draw(pat: Pattern); 
PROCEDURE TShape.Erase; 
PROCEDURE TShape.Move; 
PROCEDURE TShape.RandomRect; {Assign a random rectangle to 
fBoundRect } 
END; : 


TArc = OBJECT (TShape) 
£StartAngle, fArcAngle: INTEGER; 
PROCEDURE TArc.IArc; {Initialize fields} 
PROCEDURE TAre.Draw(pat: Pattern); OVERRIDE; 
PROCEDURE TArc.Erase; OVERRIDE; 
END; 


TRoundRect = OBJECT (TShape) : 
OvalWidth, fOvalHeight: INTEGER; {curvature of rounded corners} 
PROCEDURE TRoundRect.IRoundRect; {Initialize fields} 
PROCEDURE TRoundRect .Draw(pat: Pattern); OVERRIDE; 
PROCEDURE TRoundRect.Erase; OVERRIDE; 
* END; 


Figure 1-4 illustrates inheritance in ObjExample. TArc and TRoundRect inherit 
fBoundRect and add additional fields: fStartAngle and fArcAngle for TArc and fOvalWidth 
and fOvalHeight for TRoundRect. TArc and TRoundRect reimplement the Draw and Erase 
methods, but the Shape, Move, and RandomRect methods are inherited from TShape. 


The object that receives a method call must be of the same object type as the object- 
reference variable or a descendent object type of the object-reference variable’s type. The 
object-reference variable thisShape is declared as a variable of type TShape. In 

- ObjExample, 


thisShape .Draw (gray) ; 


is a method call. This means that objects of object types TArc and TRoundRect can be 
assigned to it. An object of type TShape is never created because TShape describes shapes 
in general, not particular shapes. Therefore, thisShape is an object reference to an object of 
some descendant of TShape. As discussed above, the Draw method is implemented 
differently in each descendant. When an object is told to execute the Draw method, it uses 
the method defined for its particular object type. Thus, if thisShape is an object of type 
TAre, it will execute TArc.Draw. Likewise, if thisShape is an object of type TRoundRecr, 
it will execute TRoundRect.Draw. 


When you create a new object type, the Object Pascal Compiler creates a method table for 
that object type that combines pointers to the methods from the ancestor with pointers to the 
methods for the new object type. Ancestor methods overridden by descendant methods are 
not included. Figure 1-9 lists the methods pointed to in the method tables for TArc and 
TRoundRect. 
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Figure 1-9 ` 
Method tables 


le fortArc ARMe 


TShape.|Shape : TShape.|Shape 
TArc. Draw TRoundRect.Draw 


TArc.Erase TRoundRect.Erase 
TShape.Move TShape.Move 
TShape.RandomkRect : TShape.RandomRect 
TAre. |Arc = : TRoundRect.|RoundRect 





Creating and freeing objects 


A new object (an instance of an object type) is created with the standard Pascal New 
procedure. When you pass New an object-reference variable, it allocates space for an 
object on the heap and assigns the handle to this space to the object-reference variable. The 
type of the object is encoded in the heap but the fields of the object are uninitialized. 
Generally, when you define an object type you provide an initialization method that you call 
immediately after creating each object with New. 


When an application no longer needs an object, you should remove it from the heap, using 
the Free method. The Free method removes objects from the heap and allows the space to 

be reused. Free is a method of TObject. For instance, in ObjExample, the statement 

next Shape .Free 

frees the object referred to by the handle contained in nextShape. You can override Free so 


that objects of a given type can perform extra cleanup tasks when they are about to be 
deallocated. 


SELF 


SELF, an Object Pascal reserved word, is an object reference. 

Any method can refer to SELF, and it always means the object that is executing the 
method. SELF is an implied parameter for every method. In addition, you can act as if 
the code part of every method is surrounded by 


WITH SELF DO 
BEGIN 


END 


In other words, every variable and method name is checked to see if it belongs to SELF. 
For example, in ObjExample 


thisShape .Draw(gray) 
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calls the Draw method for the object. Within this method, SELF refers to the same object 
thisShape did. In other words, assuming that thisShape stores a handle to an object of type 
TArc, thisShape.Draw(gray) calls TArc.Draw. Although TArc.Draw is declared 


PROCEDURE TArc.Draw(pat: pattern) 

it behaves as if it were declared 

PROCEDURE TArc.Draw (pat: pattern; SELF: TArc) 
in which 

pat = gray 

SELF = thisShape 


Important: It is illegal to declare SELF as a formal parameter for a method. It is 
automatically declared as a parameter by the compiler. Ordinary Pascal programs that 
happen to declare self as a variable, type, or constant will not cause an error, nor will 
Object Pascal programs as long as the declaration is not within a method or object 
declaration. The same rules apply for inherited. You will, however, always get a 
compile-time error if you redeclare object in an Object Pascal program. 


SELF is rarely used. It is only necessary when you need to pass a reference to the calling 
object to another routine or need to assign a reference to the current object to a variable. 


Extending an Object Pascal program 


Applications written in Object Pascal can be functionally extended with a minimum of 
difficulty because of Object Pascal’s object-type structure. In Object Pascal, you can create 
a software library that does not account for an entire set of objects, just the most general 
objects. A program can then add new objects to the set in the library without affecting the 
basic structure of the system as long as the new objects have parallel methods. For 
example, to add a new object to ObjExample so that it can draw and move ovals as well as 
arcs and rounded-corner rectangles, you would add a unit. The new unit would contain an 
additional descendant of TShape, TOval, and a descendant of TControl, TMyControl. This 
new hierarchy is shown in Figure 1-10. 
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Figure 1-10 
New Hierarchy in ObjExample 





In the main program, MObjExample, you would add the new shape to the command line 
the user chooses from. Salient parts of the new unit are listed below. The entire unit, 
UObjEx2, is listed under "Programs” at the of this chapter. 


TYPE 
TOval = OBJECT (TShape) 
PROCEDURE TOval.Draw(pat: Pattern); OVERRIDE; 
PROCEDURE TOval.Erase; OVERRIDE; 
END; 


TMyControl = OBJECT (TControl) 
FUNCTION TMyControl.NewShape(ch: char): TShape; OVERRIDE: 
{Overriden to allow for creating TOval object} 
END; 


VAR 
gMyControl: TMyControl; {a reference to an instance of TMyControl} 


PROCEDURE TOval.Draw(pat: Pattern); 
BEGIN 
Filloval (£BoundRect, pat); 
FrameQval (fBoundRect); 
END; 


PROCEDURE TOval.Erase; 
BEGIN 

EraseOval (fBoundRect} ; 
END; 


FUNCTION TMyControl.NewShape(ch: char): TShape; 
VAR anOval: TOval; 


BEGIN 
IF (ch = 'o') OR (ch = 'O') THEN 
BEGIN 
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New (anOval) ; 
anOval.IShape; 
NewShape := anOval; 
END 
ELSE 
NewShape := INHERITED NewShape (ch); 
END; 


Note that TMyControl.NewShape adds functionality and then calls the method defined by 
its immediate ancestor by calling INHERITED NewShape. TMyControl.NewShape 
extends the functionality of the function by adding an “o” command that creates an oval. 


Note the statement 


IF {ch = 'o') OR (ch = 'O') THEN 
BEGIN 
New (anOval) ; 
anOval.IShape; 
NewShape := anOval; 
END 


If the command the user enters is not an o, it must be one of the original commands that 
TControl.NewShape recognizes. The following method call is used to deal with that 
situation: 


NewShape := INHERITED NewShape (ch); 


This calls TControl.NewShape, because INHERITED invokes the method from the 
immediate ancestor of the object type defining the present method. 


There are only two changes required in MObjExample, the main program. The object- 
reference variable, control, must be defined this way: 


control: TMyControl; 
and, when the control object is created, IMyControl must be called in place of [Control. 


By passing NEW a TMyConwol-type variable instead of a TControl-type variable, you add 
the additional functionality of TMyControl to the program. 


Descendants are the Object Pascal alternative to Pascal’s variant records. An immediate 
descendant is a more specific definition of its immediate ancestor. In other words, if an 
object type defines the general characteristics of a kind of object, the immediate descendant 
inherits these characteristics and adds additional data fields or methods or reimplements 
inherited methods. In ObjExample, TShape contains fBoundRect as its only field. TArc 
and TRoundRect add fields that add information to the bounds information so those shapes 
can be defined. 


In Object Pascal, descendants are used instead of variant record parts to handle special 
cases. In PasExample, 


AShape = RECORD 
boundRect: Rect; 
CASE kind: EShape OF 
kAre: (startAngle, arcAngle: integer); 
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kRoundRect: (ovalWidth, ovalHeight: integer); 
END; 


is the record definition of AShape. Note that a variant record part is used to add startAngle 
and arcAngle to kAre. Unlike the situation with variant records, you can add a descendant 
in Object Pascal and not affect the rest of your application. You can even add the 
descendant in a unit separate from the one in which the ancestor is declared. 


Object Pascal and MacApp 


Object Pascal was developed for use with MacApp, the Expandable Macintosh Application. 
MacApp is made up of libraries of Object Pascal code with predefined object types that 
provide certain standard functions for applications, essentially implementing the Macintosh 
user interface. MacApp thus provides standard Macintosh application behavior. When you 
write a MacApp program, you add extensions to MacApp by creating object types and 
methods to perform the work of your application. 


One of the most important features of Object Pascal is that method calls are used to tell an 
object to perform a method on itself. This means that MacApp can tell one of the objects in 
your code to invoke a method. Typically, MacApp will call a method in response to a user 
action such as choosing a command from a menu. In a case like that, your object type is a 
descendant of one of the MacApp types, the MacApp object type defines methods that you 
override, and your implementation of the called method is invoked. 
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This section gives the code for the sample programs referred to in this chapter. Note that 
the purpose of these programs is educational—they are intended to illustrate the differences 
between ordinary Pascal programming and object-oriented programming using Object 
Pascal and they may not illustrate the best programming style. 


There are two programs listed in this section. The two programs are parallel, except that 
the Object Pascal program has a unit that extends its functionality and the Pascal program 
does not. 


The two programs use the MacApp typographic and structural conventions. The 
recommended MacApp structure contains a main program and units. Thus, the example 
programs each contain a main program and a unit. The Object Pascal example also includes 
an additional unit to extend the program. See the Preface for the MacApp typographic 
conventions. 

The Object Pascal example is made up of 


° MObjExample.p: the main program for the Object Pascal example, without 
extensions 


+ UObjExample.p: a unit for the Object Pascal examples 

e MODbjEx2.p: the extended Object Pascal example 
Within this chapter, the name ObjExample refers to all code in these units and the main 
program. , 
The Pascal program is comprised of 

* MPasExample.p: the main program for the Pascal example 

e UPasExample.p: the unit for the Pascal example 


Within this chapter, the name PasExample refers to both parts of the program. 
ObjExample and PasExample use QuickDraw procedures to draw shapes. To understand 


these programs, you should be familiar with QuickDraw, which is documented in /nside 
Macintosh. 
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MObjExample.p is the main program for the Object Pascal example, without extensions. — 


PROGRAM ObjExample; 


USES 
MemTypes, QuickDraw, OSIntf£, Toolintf, ObjIntf, UObjPasExample; 


VAR 
gControl: TControl; {A reference to an instance of TControl} 
ctrlRect: Rect; 
myPort: GrafPort; 


BEGIN 
{ Initialization } 
InitGraf (@thePort); {Initialize QuickDraw} 
InitFonts; {Initialize Font Manager} 
InitCursor; 
HideCursor; 
OpenPort (@myPort); 
PenNormal; 
ExaseRect (myPort .portRect) ; 


{Create an instance of TControl to interact with the user} 

New (gControl); 

SetRect (ctriRect, 5, 20, 500, 60); 
gControl.IContrel('R)oundRect, A)xrc, M)ove, Q)uit', ctriRect); 


{Run the command loop until the user types "Q" for Quit} 
gControl.Run; 


ShowCursor; 
END. 
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UObjExample.p is a unit for the Object Pascal examples 


UNIT UObjExample; {Object Pascal version of simple shape-drawing 
program} 


INTERFACE 


USES 
MemTypes, QuickDraw, OSIntf, ToolInt£, ObjIntf£: 


TYPE 


TShape = OBJECT (TObject) 
fBoundRect: Rect; {bounding box} 
PROCEDURE TShape.IShape; (Initialize fields} 
PROCEDURE TShape.Draw(pat: Pattern); 
PROCEDURE TShape.frase; 
PROCEDURE TShape.Move; 
PROCEDURE TShape.RandomRect; {Assign a random rectangle to 
fBoundRect } 
END; 


TArc = OBJECT (TShape) 
fStartAngle, fArcAngle: INTEGER; 
PROCEDURE TArc.IArc; {Initialize fields} 
PROCEDURE TArc.Draw(pat: Pattern); OVERRIDE; 
PROCEDURE TArc.Erase; OVERRIDE; 
END; 


TRoundRect = OBJECT (TShape) 
OvalWidth, fOvalHeight: INTEGER; {curvature of rounded corners} 
PROCEDURE TRoundRect.TRoundRect; {Initialize fields} 
PROCEDURE TRoundRect .Draw(pat: Pattern); OVERRIDE; 
PROCEDURE TRoundRect .Erase; OVERRIDE; 
END; 


TControl = OBJECT (TObject) 
fCommandLine: STR255; (Text displayed in the command line} 
fCommandBox: Rect; {Screen area in which command line is 
displayed} 


PROCEDURE TControl.IControliitshine: STR255; itsBox: Rect); 
PROCEDURE TControl.Draw; {Draw the command line} 
PROCEDURE TControl.Run; {Run the command loop} 
FUNCTION TControl.NewShape(ch: char): TShape; 
{Create the shape specified by user input} 
END; 


IMPLEMENTATION 
PROCEDURE TShape.IShape; 
BEGIN f 
RandomRect; {Initialize fBoundRect to random rectangle} 


END; 


PROCEDURE TShape.Draw(pat: Pattern); 
BEGIN 
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{All drawing is done in descendants. } 
“END; . 


PROCEDURE TShape.Erase; 
BEGIN 

{All erasing is done in descendants.} 
END; 


PROCEDURE TShape.Move; 
BEGIN 

RandomRect; 
END; 


PROCEDURE TShape.RandomRect; 
CONST width = 40; 
height = 40; 
minVerticalPos = 75; 
VAR randl, rand2: INTEGER; 
BEGIN 
randl := ABS(Random) MOD (screenBits.bounds.right - width); 
fBoundRect.left := randi; 
rand2 :* ABS (Random) MOD 
(screenBits.bounds.bottom - (height + minVerticalPos)); 
‘fBoundRect.top := rand? + minVerticalPos; 
fBoundRect.right := fBoundRect.left + width; 
fBoundRect .bottom := £BoundRect.top + height; 
END; 


PROCEDURE TArc.IArc; 
VAR rands, randa: INTEGER; 

BEGIN 
IShape; {Initialize inherited fields} 
rands := ABS(Random) MOD 270; 
fStartAngle := rands; 
randa :* ABS (Random) MOD 270; 
fArcAngle := randa; 

END; 


PROCEDURE TArc.Draw(pat: Pattern); 


BEGIN 
FillArc(fBoundRect, fStartAngle, fArcAngle, pat); {Quickdraw 
calls} 
FrameArc(fBoundRect, fStartAngle, fArcAngle); 
END; 
“PROCEDURE TArc.Erase; 
BEGIN 
EraseArc (fBoundRect, fStartAngle, fArcAngle); (Quickdraw call} 
END; ` 


PROCEDURE TRoundRect.IRoundRect; 

BEGIN 
IShape; {Initialize inherited fields} 
fOvalWidth := 20; 
fOvalHeight := 15; 

END; 


PROCEDURE TRoundRect .Draw (pat: Pattern); 
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BEGIN 
FillRoundRect (fBoundRect, fOvalWidth, fOvalHeight, pat); 
FrameRoundRect (fBoundRect, fOvalWidth, fOvalHeight); 
END; 


PROCEDURE TRoundRect.Erase; 
BEGIN 

EraseRoundRect (fBoundRect, fOvalWidth, f£OvalHeight) ; 
END; 


PROCEDURE TControl.IControl(itsLine: STR255; itsBox: Rect); 
BEGIN 2 ; 

fCommandLine := itsLine; 

fCommandBox := itsBox 
END; 


PROCEDURE TControl.Draw; 
VAR commandLine: STR255; 
BEGIN 
‘ExraseRect (fCommandBox) ; 
MoveTo (fCommandBox.left, fCommandBox.bottom) ; 
commandLine := £CommandLine; {This is necessary because 
f DrawString may compact the heap, 
making a reference to a field in a 
call to DrawString possibly 
dangerous. } 
DrawString (commandLine) ; 
END; 


PROCEDURE TControl.Run; 
VAR ch: CHAR; 
thisShape: TShape; 
nextShape: TShape; 
theEvent: EventRecord; 


BEGIN 

thisShape := NIL; 

nextShape := NIL; 

{Draw the command line} 

Draw; 

REPEAT 
{Accept a character typed from the keyboard} 
IF GetNextEvent (keyDownMask, theEvent) THEN 


BEGIN 
ch := CHAR (BAND (theEvent.message, charCodeMask) ); 
CASE ch OF 
'm', ‘Mt: 
IF thisShape <> NIL THEN 
BEGIN 
thisShape.Erase; (Erase shape from present 
location} 
thisShape.Move; {Assign it a new location} 
thisShape.Draw(gray); {Draw it in its new location} 
END; 
OTHERWISE 
BEGIN 
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nextShape := NewShape(ch); {returns NIL if ch 


IF nextShape <> NIL THEN 
BEGIN 
IF thisShape <> NIL THEN 
BEGIN 


unrecognized} 


thisShape.frase; {Erase the old shape} 
thisShape.Free; {Deallocate it from the heap} 


END; 
thisShape := nextShape; 


thisShape.Draw(gray); {Draw the new shape} 


END; 
END; 


END; {CASE} 
END; {IF GetNextEvent } 
UNTIL (ch = 'q') OR (ch = 'Q'); 
END; 


FUNCTION TControl.NewShape(ch: CHAR): TShape; 
VAR anArc: TArc; 
. aRoundRect: TRoundRect; 
BEGIN ' 


IF (ch = 'a') OR (ch = 'A') THEN 
BEGIN 
New (anArc}; 


anArc.IArc; 
NewShape :» anArc; 


END 

ELSE IF (ch = 'r') OR (ch = 'R') THEN 
BEGIN 
New (aRoundRect) ; 


aRoundRect .TRoundRect; 
NewShape := aRoundRect; 
END 
ELSE 
NewShape := NIL; 
END; 
END. 
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MPasExample.p is the main program for the Pascal example. i 


PROGRAM PasExample; 


USES 
MemTypes, QuickDraw, OSIntf, ToolIntf, UPasExample; 


VAR 
ctriRect: Rect; 
myPort: GrafPort; 


BEGIN - 
{Initialization} 
InitGraf (@thePort); (initialize QuickDraw} 
InitFonts; {initialize Font Manager} 
InitCursor; 
HideCursor; 
OpenPort (@myPort) ; 
PenNormal; i 
EraseRect (myPort.portRect) ; 
SetRect (ctrlRect, 5, 20, 500, 60); 
{Run the command loop until the user types "Q" for Quit} 
Run('R)oundRect, A)re, Mjove, Q)uit', ctriRect); 
ShowCursor; 

END. 
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UPasExample.p is the unit for the Pascal example 


UNIT UPasExample; {Normal Pascal version of simple shape-drawing 
program} 


INTERFACE 


USES 
MemTypes, QuickDraw, OSIintf, Toollintf; 


TYPE 


EShape = (kArc, kRoundRect); 
TCmdLine = String[80]; 


TShape = *PShape; 
PShape = “ASnhape; 


AShape = RECORD 
boundRect: Rect; {bounding box} 
CASE kind: EShape OF 
kArc: (startAngle, arcAngle: INTEGER); 
kRoundRect: (ovalWidth, ovalHeight: INTEGER) ; 
END; 


PROCEDURE Run(commandLine: TCmdLine; commandBox: Rect); 
IMP LEMENTATION 


PROCEDURE DrawShape(pat: Pattern; SELF: TShape); 
BEGIN : 
CASE SELF**.kind OF 


kArc: 
BEGIN 
FillArc(SELF**.boundRect, SELF**.startAngle, 
SELF**.arcAngle, pat); 
FrameArc (SELF**.boundRect, SELF**.startAngle, 
SELF**.arcAngle); 
END; 


kRoundRect: 
BEGIN 
FillRoundRect (SELF**.boundRect, SELF**.ovalWidth, 
SELF**.ovalHeight, pat); 
FrameRoundRect (SELF**.boundRect, SELF**.ovalWidth, 
SELF** .ovalHeight) ; 
END; 


END; 
END; 


PROCEDURE EraseShape (SELF: TShape) ; 
BEGIN 
CASE SELF“**. kind OF 


kKArC: 
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EraseArc (SELF** .boundRect, SELF**.startAngle, 
SELF** ,arcAngle) ; 


kRoundRect: 
EraseRoundRect (SELF**.boundRect, SELF**.ovalWidth, 
SELF**.ovalHeight) ; 


PROCEDURE RandomRect (SELF: TShape); 
CONST width = 40; 
height = 40; 
minVerticalPos = 75; 
BEGIN 
SELF“*.boundRect.left := ABS (Random) MOD (screenBits.bounds.right 
- width); 
SELF** .boundRect.top := ABS(Random) MOD (screenBits.bounds .bottom 
~ (height + minVerticalPos)) + 
minVerticalPos; 
SELF** .boundRect.right := SELF**.boundRect.left + width; 
SELF** .boundRect .bottom := SELF**.boundRect.top + height; 
END; 


FUNCTION NewAre: TShape; 

VAR rands, randa: INTEGER; 
SELF: TShape; 

BEGIN 
SELF := POINTER (NewHandle (SizeOf (AShape) )); 
RandomRect (SELF) ; 
rands := ABS (Random) MOD 270; 
SELF“**.startAngle := rands; 
randa := ABS (Random) MOD 270; 
SELF**.arcAngle := randa; 
SELF** .kind := kAre; 
NewAre := SELF; 

END; 


FUNCTION NewRoundRect: TShape; 
VAR SELF: TShape; 
BEGIN 
SELF := POINTER (NewHandle (SizeOf ({AShape) )); 
RandomRect (SELF) ; 
SELF** ovalWidth := 20; 
SELF““*.ovalHeight := 15; 
SELF**.kind := kRoundRect; 
NewRoundRect := SELF; 
END; 


PROCEDURE Run(commandLine: TCmdLine; commandBox: Rect); 
VAR ch: CHAR; ‘ 
theShape: TShape; 
theEvent: EventRecord; 
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BEGIN 
theShape := NIL; 
{Draw the command line} 
EraseRect (commandBox) ; 
MoveTo (commandBox.left, commandBox.bottom) ; 
DrawString (commandLine) ; 


REPEAT 
{Accept a character typed from the keyboard} 
IF GetNextEvent (keyDownMask, theEvent) THEN 


BEGIN 
ch := CHAR(BAND(theEvent.message, charCodeMask)); 
CASE ch OF 
'm', tM’: 5 
IF theShape <> NIL THEN 
BEGIN 
EraseShape(theShape); {Erase shape from present 
, location} 
RandomRect (theShape); {Assign it a new location} 
DrawShape (gray, theShape); (Draw it in its new 
location} 
END; 
rt, IR, tal, 1AM: 
BEGIN 
IF theShape <> NIL THEN 
BEGIN 
EraseShape (theShape); {Erase the old shape} 
DisposHandle (Handle (theShape)); {Deallocate it from 
f the heap} 
END; 
IF (ch = 'r') OR (ch = 'R') THEN 
theShape := NewRoundRect 
ELSE 
theShape := NewArc; 
DrawShape(gray, theShape); {Draw the new shape} 
END; 
END; {CASE} 


END; {IF GetNextEvent} 
UNTIL (ch = 'q') OR (ch = 'Q');? 
END; 
END. 
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MODbDjEx2.p is the extended Object Pascal program. 


PROGRAM UObjJEx2; {Demonstration of adding a new object type, TOval} 


USES f 
`. MemTypes, QuickDraw, OSIntf, ToolIntf, ObjIntf, UObjPasExample; 


TYPE 
TOval = OBJECT (TShape) 
PROCEDURE TOval.Draw(pat: Pattern); OVERRIDE; 
PROCEDURE TOval.Erase; OVERRIDE; 
END; 


TMyControl = OBJECT (TControl) > fe 
FUNCTION TMyControl.NewShape(ch: char): TShape; OVERRIDE; 
{Overriden to allow for creating TOval object} 

END; 


VAR 
gMyControl: TMyControl: {a reference to an instance of TMyControl} 
ectriRect: Rect; $ 
myPort: GrafPort; 


PROCEDURE TOval.Draw(pat: Pattern); 
BEGIN 
Filloval(fBoundRect, pat); 
FrameOval (fBoundRect) ; 
END; 


PROCEDURE TOval.Erase; 
BEGIN 

EraseOval (fBoundRect) ; 
END; 


FUNCTION TMyControl.NewShape (ch: char): TShape; 
VAR anOval: TOval; 
BEGIN 
IF (ch = 'o') OR (ch = 'O') THEN 
BEGIN 
New (anOval); 
anOval.IShape; 
NewShape := anOval; 


END 
ELSE 
NewShape := INHERITED NewShape(ch) ; 
END; 
BEGIN 
{Initialization} 
InitGraf(@thePort); {Initialize QuickDraw} 
InitFonts; {Initialize Font Manager} 
InitCursor; 
HideCursor; 
OpenPort (@myPort) ; 
PenNormal; 


EraseRect (myPort.portRect); 


{Create an instance of TControl to interact with the user} 
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New (gMyControl); 

SetRect (ctrlRect, 5, 20, 500, 60); 

gMyControl.IControl('R)oundRect, A)rc, O)val, M)ove, Q)uit', 
etrlRect); 


{Run the command loop until the user types Q for Quit} 
gMyControl.Run; 5 


ShowCursor; 
END. 
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Chapter 2 
How MacApp Works 


What MacApp does 


Macintosh applications are characterized by 
e Windows 
e Menus 
¢ Use of the mouse 
e Being event-driven, that is, acting in response to user generated events, 
particularly mouse, keyboard, and menu commands 


Although this common structure makes Macintosh applications easy to learn and use, it 
makes them difficult to program in the traditional way. MacApp was written to take care of 
most of the standard behavior of a Macintosh application. Because it is written in an 
object-oriented fashion, you can write your application as an extension of MacApp, 
essentially particularizing the generalized objects provided by MacApp. 


The structure of MacApp 


MacApp declares six major object types. As you might expect from the object-oriented 
model, each basic object type corresponds to a conceptual entity. Figure 2-1 shows five of 
those basic conceptual entities: the view, frame, window, document, and application. The 
sixth entity, which is not shown, is the command. 
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Figure 2-1 
MacApp conceptual entities 
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When you start a MacApp application, your main program creates and initializes the 
application object, and then calls the Run method for that object. Generally, a command is 
then issued to open an old or create a new document. A method of your application is 
called to create a document object. If you are opening an old document, the document 
object reads the data stored on disk. In any case, the document object creates the view, 
frame, and window objects. 


The view object controls the view, which you can think of as being a surface on which an 
interpretation of the document’s data, or other information important to the application user, 
is displayed. 


The frame object controls the frame, which is part of what users see as the window. 
Specifically, the frame is made up of the scroll bars and the content area of the window. 
The content area of the window shows part of the view; which part is determined by the 
position of the elevators in the scroll bars. 
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The window object controls the window, which is the rest of what the users see as the 
window on the screen. In MacApp, the window is made up of the title bar, the close icon, 
the size icon, and (with the Macintosh Plus ROM) the zoom icon. 


The sixth group of objects defined by MacApp are command objects. Command objects 
are created by other objects to handle commands. Typically, one of the five objects just 
described creates a command object to somehow change itself. For example, the document 
object creates a command object to change some of the document's data. The view object 
might create a command object to change the reduction factor used in displaying the 
document. Command objects are nearly always created to carry out commands given by 
the user. 


At any time, there is only one application object. 


Applications can have more than one document object at a time, each one generally 
corresponding to a desktop document. 


Documents can have more than one view. Different views show different aspects or 
interpretations of the document’s data or show other information necessary for the use of 
that document. (An example of the latter is a palette view, such as the palette in 
MacDraw™, A palette view shows tools that can be used to modify the document’s dara.) 


Each view that is displayed on the screen is shown in a frame. (Views also may be 
undisplayed, but that is presumably a temporary state, as views exist to display 
information.) ` 


Every frame is displayed in a window. A window can contain any number of frames, all 
of which show views belonging to the same document. Itis also possible to have a 

. window belonging to the application as a whole, disassociated from any particular 
document, such as a palette in MacPaint™. 


Finally, command objects are created as needed to carry out user commands. Once the 
command has been done, the command object is kept so it can undo the command if 
necessary (and possible). Then, when a new command object that changes the document’s 
data or is undoable is created, the old command is told, if necessary, to finish its actions. It 
is then freed. 


This discussion is intended to be a conceptual introduction. The structure and duties of 
these basic object types and the other object types defined in the MacApp package are more 
fully described later in this chapter. 


The target chain and the cohandler chain 


As mentioned before, Macintosh applications are event-driven. The Macintosh Event 
Manager collects events from the keyboard, mouse, and other devices, packages the events 
in event records, and passes the records to the application when the application requests 
them. 


In a MacApp application, the MacApp code periodically requests events from the Event 


Manager and handles the events or repackages them and calls your code to handle them. In 
cases such as a mouse down in the menu bar or title bar of a window, MacApp handles the 
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event. Methods of application objects are called when and if the user actions resolve into 
actions that require application action. 


When MacApp calls one of your methods, the method called depends on the type of event. 
DoMenuCommand (and possibly DoSetupMenus) is called when a menu command is 
chosen; DoMouseCommand is called when the mouse goes down in an application view. 
Each of those “event handling” methods are declared for a basic MacApp object type, 
TEvtHandler. An object of type TEvtHandler is called an event handler. Application, 
document, window, frame, and view objects are all descendants of TEvtHandler and, so, 
are themselves event handlers. TEvtHandler has a field fNextHandler, and this field is 
used to put the application, document, window, frame, and view together in a singly linked 
list. - i 


In most cases, MacApp cannot independently determine what event handler should handle a 
particular event. Your application identifies the object most likely to handle events by 
making it the target stored in the global variable gTarget. Events are passed to the target 
first. After that, the event follows the target chain. 


The target chain is the chain of event handlers starting with the target. If the target is the 
view (as it most often is), the target chain passes events (and some other actions) to your 
view’s method, and then to the corresponding methods of TView, TFrame, TWindow, 
TYourDocument, TDocument, TYourA pplication, and TApplication. 


The target chain begins with MacApp calling a method of gTarget. That method either 
begins or ends by calling the INHERITED method. As each inherited method (except that 
of TEvtHandler) also calls the INHERITED method, this eventually leads to the 
TEvtHandler method. The TEvtHandler method always tells SELF.fNextHandler to 
handle the event. The same process of INHERITED method calls and calls to 
fNextHandler methods is followed until fNextHandler is NIL. The view, frame, window, 
document, and application objects are linked together (in that order) in a list by each being 
fNextHandler of the next. The end of the list is the application (that is, its fNextHandler is 
always NIL), and the head of the list is most often the view. Note that the target chain can 
have different members at different times, because a window can be fNextHandler for 
several frames, a document can be fNextHandler for several windows, and the application 
can be fNextHandler for several documents. The current target, and hence the target chain, 
depends on what is currently active. Figure 2-2 illustrates the target chain. 
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Figure 2-2 
The target chain 
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This structure means that if, for example, the target is the view, every object in the chain 
gets a chance at the event. If, however, there are additional views, they do not get a chance 
at the event, because they are not in the same target chain. Applications with special needs 
can relink the target chain to allow other items to get a chance at the event. 


Of the methods that use the target chain, some always pass the event along, and some pass 
it along only under certain conditions. For example, DoSetupMenus always begins by 
calling INHERITED DoSetupMenus, so other objects get to set up the menus before the 
target makes its changes; DoMenuCommand, on the other hand, first checks if the menu 
command is one it handles and then calls INHERITED DoMenuCommand if it does not. 


Note, also, that the target chain is used when there isn’t an event in the event manager 
sense. For example, when there are no events, and the menus may have changed, MacApp 
calls target. DoSetupMenus to save time at the next menu event. Also, MacApp calls 
target.Doldle when there is nothing else to do. (Doldle is passed through the list using a 
somewhat different mechanism. Each event handler has a field that tells MacApp whether 
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or not Doldle should be called for that object. A MacApp method scans through the target 
chain and calls Doldle for the objects that want Doldle called.) 


Every window has a field, fTarget, which, when the window is inactive, holds a reference 
to the object that should be the target when that window is next activated. In general, you 
initialize fTarget to the. window’s primary view. In general, you need to assign gTarget 
only when there are multiple frames in a window and the user makes a selection in one of 
the framed views. 


This target chain suffices for the basic set of event handlers. However, you sometimes 
create your own event handlers, usually to handle asynchronous events such as network 
events, and these event handlers are not in the target chain. MacApp maintains the 
cohandler chain for these event handlers. When you create such.an object, you install it 
in the cohandler chain by calling gApplication.InstallCohandler. Alien events, which are 
events other than user input that do not fit into the categories handled by the methods that 
use the target chain, are passed through the cohandler list. An example of an alien event is 
a packet received on the AppleTalk™ network. 


The MacApp units and their object types 


The MacApp units UObject, UMacApp, UList, UTEView, UDialog, and UPrinting define 
a number of object types, plus a number of global routines, variables, and ordinary types. 
All object types you deal with are described in a general way in this chapter. 


More specific information for all object types, methods, and fields you may use or 
customize is in Chapter 10. Global routines, variables, constants, and types you may use 
are documented in Chapter 9. Globals, methods, and fields that are only used for 
debugging are documented in Chapter 11. 


Note: There are some methods, fields, and globals that are used internally by MacApp 
and are never, or almost never, used in applications and which therefore are not 
documented in this manual. See the MacApp code for the details of those elements. 


Figure 2-3 is a diagram of the tree of object types used in MacApp programs. In the figure, 


arrows indicate descent and gray boxes holding outline text show object types you always 
create. You also usually create additional descendants. 
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Figure 2-3 
The tree of object types 
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UObject 


Every MacApp program uses UObject. Primarily, this unit defines TObject, the ancestor 
object type for all objects. It also defines a few compilation flags and global variables and 
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routines, including those that implement the failure-handling mechanism used in MacApp 
programs. i . 


TObject 


The TObject type is the ancestor for all object types. TObject itself is never instantiated, but 
-İt is often used to define object-reference variables that can hold references to any object. 
You can use the type-coercion feature to access fields and‘methods not defined for TObject. 
(TObject has no fields, but it does have a few methods.) 


TObject has no ancestor. — - 
What it does 


TObject defines a set of utility methods that are available, and often used, for all objects. 
Those methods deal with cloning and freeing objects. “Cloning” means making an exact 
copy of an object, and returning a reference to the new object. “Freeing” means 
deallocating the memory space allocated for the object, thereby losing all data stored in the 
object’s fields. There are two levels of each operation: a shallow level and a full level. The 
shallow operation frees or clones only the object itself. All objects automatically inherit that 
capability from TObject. The full operation frees or clones any objects referred to by fields 
of the object, as well as the object itself. Descendants must implement that capability to the 
extent itis needed; TObject can merely define the interface for it. In fact, for TObject, the 
method for the full operation simply calls the shallow method, and so the two have identical 
results. You never override the shallow methods; instead, you override the full methods 
when you need additional action. 


Where it fits in 


You never create instances of TObject. You often instantiate or customize descendants of 
TObject defined in MacApp or other units, and you often create your own descendants of 
TObject to store your data. 


UList 


UList defines TList, a simple list (actually, dynamic array) object type provided for 
convenience and efficiency. Because MacApp uses these lists, every MacApp program 
must use UList. 


TList 


The list type implements a simple list. It can hold lists of any type of object, as its element 
type is TObject. It is used throughout MacApp to store lists of objects and can be used 
freely in applications for the same purpose. 
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What it does 

A TList object is able to hold any number of object references. You can obtain any element 

by index, get the first element, add an element to the beginning or end of the list, delete an 
element or all elements, use an enumeration method to apply a repetitive operation to all 


elements in the list, and use another enumeration method to apply a functional test to all 
members of the list until the function returns TRUE. 


Where it fits in 


TList is used by MacApp and its units to organize data. You do not have to use it. 
Basically, a TList object serves the same purpose in a MacApp program as an array serves 
in a less dynamic Pascal program: it allows you to perform repetitive operations on a group 
of items more easily than you otherwise could. 


UMacApp 


Every MacApp program uses the main MacApp unit, UMacApp. It defines many types, 
constants, global variables, and procedures, including the object types TEvtHandler, 
TApplication, TDocument, TView, TFrame, TWindow, TCommand, TPrintHandler, and 
TDeskScrapView; some ordinary Pascal types; constants for the standard menus and 
commands; constants for alert numbers; and constants for resource ID’s. 


TEvtHandler 


The event handler type is used as the ancestor for most object types in MacApp that can 
receive input from the user or the network. You never create instances of TEvtHandler. 
You always create instances of descendants of TEvtHandler. 


TEvtHandler is an immediate descendant of TObject. 


What it does 
TEvtHandler defines a method interface and some default methods to handle the following 
types of events in a Macintosh application: 

e key events (typing) 

e mouse events 

e auto-repeat key events (keys held down to repeat) 


e menu events, from menu items chosen both with the mouse and with Command-key 
combinations 


e termination events, which occur when the user quits the application 
e idle events, which MacApp generates when no other events are pending 
e network events (or, more generally, alien events) 
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You never create instances of TEvtHandler, and most programs never customize 
TEvtHandler. You do, however, create instances and descendants of a number of 
descendants of TEvtHandler. In fact, with the important exception of TCommand, most 
MacApp object types that you deal with are descendants of TEvtHandler. Most of the 

‘ methods you override for the objects that are descended from TEvtHandler are defined for 
TEvtHandler, although the default implementations of those methods provided by 
TEvtHandler usually do nothing. 


Each event handler has a field fNextHandler, which is used to link the event handlers 
together into, in the simplest case, a chain. One of the event handlers is the current target, 
and is stored in the global variable gTarget. When an event occurs, it is sent to gTarget. If 
the target cannot handle the event, it sends it on to the next handler in the chain. 


The chain is generally organized as follows: a view, a frame, a window, a document, and 
the application. Because an application can have more than one document, a document can 
have more than one window, and a window can have more than one frame, the event 
handlers generally form a tree structure. The root of the tree is the application object. The 
leaves of the tree are views. The links (fNextHandler) point from the leaves toward the 
root. 


The target is usually a view, but it may be some other object. For example, when no 
windows are open, the application is the target. Note that events are never sent away from 
the root, so if the target is the window, the view does not get any events. Also, each view, 
frame, window, and document is normally in a separate target chain, so events do not cross 
from one branch of the tree to another. (See “The Target chain and the cohandler chain” 
earlier in this chapter for a more complete discussion of the use of gTarget.) 


The standard ordering of event handlers allows, for example, a view to intercept an event 
normally processed by its document or the application and to handle it in a special way. 
You can obtain a nonstandard ordering to address unusual needs by manipulating 
fNextHandler fields after you initialize object structures. 


TApplication 

You customize TApplication to create the application object type for your program. 
Methods of TApplication implement the main event loop. The application’s main event 
loop receives events and dispatches them to other objects. When there are no events, the 
main event loop does some idle-time tasks. The main event loop is implemented in 
TApplication.MainEventLoop; you can override it, if you want, but that is relatively rare. 
Only one application object exists during execution of a MacApp program. 


TApplication is an immediate descendant of TEvtHandler. 


What it does 


The application handles the main event loop. The main event loop receives incoming 
events from the event queue and dispatches them to the appropriate objects. Most mouse 
events are sent to the window in which the mouse pointer was located when the button was 
pressed. (Sometimes that means simply activating the window.) If the mouse event 
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resulted in the user choosing a menu command, MacApp translates that action to a menu 
event. Menu events and key events are dispatched to gTarget. If the receiver of an event 
doesn’t handle the event, it passes it to the next event handler in the linked list of handlers 
of which it is a part. The last handler in every linked list is the application object. The 
application itself generally handles commands to open a new or old document, print 
documents from the Finder, open and close a window, close a document, and quit. 


For efficiency, the application object has no fields. Most global variables are used as if 
they were fields of the application object. 


Where it fits in E 


You create the application object in your main program, initialize it, and then call the 
method TApplication.Run. Run contains the event loop. It loops, calling other methods in 
. Tesponse to user and network actions, until the user chooses Quit from the File menu. 


You have to override TApplication.DoMakeDocument to make your own type of document 
(that is, to allocate and initialize a document object). You rarely override other methods of 
TApplication. 


An application can have any number of documents open at the same time. The document 
objects are kept in a list object. 


TDocument 


A document object stores the data for a document. When the user opens a document icon, _ 
some or all of the data stored in the file represented by the icon is loaded into data structures 
maintained by the document object. 


An application may declare more than one document object type. An application may 
instantiate more than one document object at a time. An application that doesn’t store any 
permanent data in documents need not use document objects at all. 


A simple application defines one immediate descendant of TDocument. The descendant is 
used to create the document object when a new document is created or when an old 
document is opened. The document object is freed when the user closes the document. 


TDocument is an immediate descendant of TEvtHandler. 


What it does 


The document object stores the document’s data. (The data may actually be stored in a 
separate structure or even left on the disk, but you must always be able to reach it through 
the document.) A document closes itself when told to by the application and tells its 
windows to open and close as needed. It handles Revert commands. Most importantly, 
the document should have methods to add and delete data in its data set and should handle 
most commands that change data. 
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When your application starts, the DoMakeDocument method of your application object is 
called. DoMakeDocument creates a document object. The data set of that particular 
document is stored in the document object. 


Your document object type must implement DoMakeViews. MacApp calls that method to 
create the view object or objects for the document. The view object interprets and displays 
the document’s data. You can have more than one view object associated with a given 
document, each of which may interpret the document’s data in a different way. (View 
objects also may display information that is not part of the document’s data. See “TView” 
in this chapter.) 7 


The document object handles events related to the document as a whole or events related to 
the data that are independent of the way the data is displayed. For example, a document 
object saves its data to a disk file, an action involving the data and not its visual 
representation. Commands that edit the data set are also generally directed at the document. 


A document normally has one or more windows associated with it. Windows are kept in a 
list. 


TFrame 


A frame is a rectangular area visible within a window. Within a frame is displayed either a 
portion of a view or a collection of subframes. Frames can be used to subdivide a window 
into fixed areas that differ from each other in content or appearance. The container of the 
outermost frames is the window. Because every container of a frame is a frame, the 
window must be a frame. Therefore, TWindow is an immediate descendant of TFrame. 
Typically, subdivisions of a window are not themselves subdivided, but they may be. 


A frame also has a list of Control Manager controls that it may contain. A frame usually 
has two scroll bars that control it. The scroll bars are in the control list of the containing 
frame, which is usually the window. 


TFrame is an immediate descendant of TEvtHandler. 


What it does 

The basic purpose of a frame is to display a view. You can think of a frame as a 
rectangular area which can be maneuvered around the view with the use of the scroll bars. 
The same frame can show different views at different times. 

A frame usually acts in response to requests from other objects, usually the contained view 


or the containing window. The most common operation is drawing the visible portion of 
the view. The next most common operation is scrolling. 


Where it fits in 


Every frame can be the container of another frame, or of several frames, or it can look on a 
view. A window is a special case of a frame. 
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In the simplest (and most common) case, the window contains a single frame which looks on a 
view. Also fairly common is a window that is divided between two frames, both contained by the 
window and each looking on different views. A window can be divided into any number of 
frames; similarly, a frame can be divided into any number of subframes, although frames rarely 
are. i 


A frame knows about the local coordinate system of its view. Before telling the view to 
draw, the frame focuses, that is, it sets up the grafPort origin and clipRgn so that the 
view can make QuickDraw calls with coordinates in its own coordinate system. See 
Chapter 4 for a discussion of QuickDraw, grafPorts, clipRgn, and coordinate systems. 


TWindow 


Windows are the familiar rectangular objects that have title bars and (usually) size boxes 
and close boxes and can be moved around the screen. Everything displayed by an 
application, except for menus, is in a window. Modeless dialog boxes are special cases of 
windows. Modal dialog boxes and alerts are windows in the Window Manager sense, but 
MacApp does not bother to create a TWindow-type object for a modal dialog or alert, 
because they are transitory, or for desk accessories, because they do not belong to the 
application. See “UDialog” in this chapter for more information on dialog boxes. 


TWindow is an immediate descendant of TFrame. 


What it does 


The activities primarily associated with windows include the following: 


e Activate/Deactivate. When the user clicks in an inactive window, the window is 
activated and any previously active window is deactivated. 


e Move. The user moves a window by dragging it around by the title bar. MacApp 
automatically updates the frames. 


e Resize. The user changes the size of a window by dragging the size box. MacApp 
automatically updates the frames. 


Where it fits in 


Most windows belongs to a document. The windows for a particular document are kept in 
a list in the document object. Windows can also belong to the application, in which case 
they are called free-standing windows, but that is relatively uncommon. 


The application creates one window object for each document and application window on 
the screen. A window is opened either when its document is opened or subsequently, in 
response to some other event, such as a menu command. 


Every window contains at least one frame. Scroll bars belong to frames, not to. windows. 


Frames, not windows, look on views. Any number of frames, and hence any number of 
views, can be displayed in a window. 


Final page 2-]3 


-MacApp Programmer’ s Guide How MacApp Works 


Note: Technically, a window is itself a frame and can look directly on a view, as 
long as you do not need scroll bars, a size box, and subdivisions, but this is rarely 
done. 


TView 


A view is a representation of data in a two-dimensional form that can be printed on paper or 
displayed on the screen. A view is what makes it possible for the user of your application 
to see a document’s data or other data relevant to the application. 


A document can have any number of view objects, each of which may display the 
document’s data in a different way. View objects can come and go, so the way the data is 
displayed can change in response to commands or other events. 


In addition to displaying interpretations of the document’s data, views may display other 
information. For example, a palette view (such as the ones in MacPaint and MacDraw) 
shows a group of application-defined operations. 


A view belongs to a frame when it is displayed. 


A view is a rectangular area of any size up to 32,000 pixels in each dimension. It can be 
larger than the screen. If a frame can be scrolled, it can scroll to any part of its view. A 
view has its own coordinate system. All coordinates should be non-negative and less than 
32,000. 


The relationship of the coordinate system of a view to the other coordinate systems in 
MacApp is explained in Chapter 4. 


TView is an immediate descendant of TEvtHandler. 


What it does 


The main responsibility of a view is to draw any part of itself when requested to do so. 

The amount of the view that is drawn depends on what object requests the drawing and 
how much has changed since the last time the view was updated. If the frame asks the 
view to draw itself, then only the portion of the view visible in the frame need be drawn. If 
a print handler asks the view to draw itself, then only the portion visible on the current page 
need be drawn. The view doesn’t know where the drawing request came from; the 
drawing request includes a parameter that identifies the part of the view that must be drawn. 


Another responsibility of the view is to keep track of and highlight the selection. 


The view must create a command object to track the mouse whenever the mouse button is 
pressed in the view. This object provides feedback as the user moves the mouse. 


A view also handles some menu commands that affect the appearance of the view but do 
not change the data. 


Final page 2-14 


‘How MacApp Works MacApp Programmer's Guide 
Where it fits in 


You need views to display information for the user. Many views map between stored data 
(usually in the document object) and its graphic representation on the screen or the printed 
page. Other views show information that enables the user to use the application. 


Every frame displayed in any of the document’s windows may have a view object 
associated with it. When the user uses the scroll controls, if any, of the frame, the frame is 
moved around the view. 


A single frame can show different views at different times. 


When a command changes the appearance of a part of the view, you invalidate that part 
of the view. The next time the application updates the view, it passes the union of all 
invalidated areas to the view to be redrawn. i 


Your application calls QuickDraw drawing routines to draw in views and only in views. 
Code in MacApp.u takes care of drawing the menu bar, the menus, and the rest of each 
window and frame, such as the scroll bars and the title bar. 


TCommand 


When the user chooses a menu command, uses a Command-key combination, types, or 
presses the mouse button, a command object is usually created. A command object is a 
transitory object that performs some particular action and can usually undo and redo the 
action. There are many different kinds of command objects in programs; the major division 
is between those command objects, called mouse command objects or trackers, that 
track the mouse while the mouse button is down and those that do not involve mouse 
tracking. 


Figure 2-4 illustrates a simple command object; Figure 2-5 illustrates a mouse command 
object. Note that, in the diagrams, command objects are returned to MacApp by the 
methods DoMenuCommand and DoMouseCommand (and also by 
TCommand.TrackMouse). A number of other methods return command objects for 
different purposes. Once the command object has been returned to MacApp, MacApp calls 
the methods of the command object, listed in the boxes below the command object, to carry 
out the actions required by the command. 
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Figure 2-4 
A simple command 
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Figure 2-5 
A mouse command 
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Whatever the action is, a command object is created when the user begins an action and is 
freed when the action can no longer be undone or redone. (Redoing an action is undoing 
the action an even number of times. In other words, the first time the user chooses Undo 
the action is undone. The second time the user chooses Undo the action is redone. 

MacApp toggles the text of the Undo menu command so it says Redo when appropriate.) 


Not all command objects are obviously commands. For example, typing on the keyboard 
is ultimately handled by a command object created by a method not shown in the figures, 
DoKeyCommand. l 


You don’t have to create a command object to handle a command. You must create a 
command object when you want the user to be able to choose Undo to undo the effects of 
the command. Otherwise, you are free to carry out the action of the command without 
creating a command object. (In that case, the action of the command is carried out in 
DoMenuCommand or DoMouseCommand.) You often create a command object even 
when a command is not undoable. For example, you can’t track the mouse without a 
mouse command object, so mouse actions involving motion always are carried out by 
command objects. 


The following kinds of actions are handled by command objects: 


-+ Key commands. These commands are created when the user presses a key, and 
usually stay in existence until the user changes the document in some way other than 
typing. 
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e Menu commands. These commands are created when the user chooses a menu item, 
and are freed when the command is no longer undoable or redoable. A single type of 
command object may handle a group of related menu commands. 


e Mouse trackers. These commands are created when the user presses the mouse 
button while the pointer is in a view within a frame. The command object may give 
feedback to the user as long as the mouse button is down. There are a number of 
different common types of mouse trackers: selector command objects, which track the 
mouse while the user selects something; dragger command objects, which track the 
mouse when the user drags something from one place to another; and sketcher 
command objects, which track the mouse when the user draws a new graphic shape. 
Some mouse command objects handle a number of different kinds of commands. 
‘Note that, as shown in Figure 2-5, you can change to a different mouse command 
object while tracking the mouse. 


Unlike other command object types, for which you usually override only Dolt, 
Undolt, and Redolt, you always override TrackMouse and often override 
TrackFeedback for mouse trackers, and you may or may not override Dolt, Undolt, 
and Redolt. TrackMouse is called repeatedly while the mouse button is down. 


After the action is finished, if the command changes the document, the command object 
remains in existence in case the user wants to undo the command. After undoing the 
command, the user can redo it. When a new command that changes the document is 
initiated by the user, MacApp calls the Commit method for the old command, thus 
committing the command, and frees the old command object. Therefore, there can be (at 
most) two command objects in existence at a time: the command just completed (and about 
to be committed), and a new command that is being initiated. 


Note: The reason for the Commit method is that, in some cases, actually doing and 
undoing a command can take too long. Instead, the command object changes the visual 
appearance of the data by applying a filter to the data, so that it appears to the user as if 
the command has been done. Then, if the user wants to undo the command, the filter is 
simply removed. Finally, when the command can no longer be undone (because the 
user gives a new command or quits the application, for example), Commit is called so 
that the command can change the data. Commit is not called if the user had left the 
command undone. For most commands, filters are not needed and the default Commit 
method, which does nothing, is used. 


TCommand is an immediate descendant of TObject. 


What it does 


What command objects do varies greatly: some commands select part of the document, 
some change the document, some change the way it is viewed, some toggle state variables, 
and so on. i 


If a command changes the document (that is, changes the data stored in the document), the 
command object has the responsibility to do the command, to undo the command, and to 
redo the command. (To redo is to reverse the effect of undoing the command.) When the 
command can no longer be undone or redone, then the command object commits the ` 
command. (For most commands, the Commit method does nothing.) 


If a command only changes the view (that is, it only changes the appearance of the data and 
not the data itself}, the command object doesn’t have to be able to undo the command. (In 
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fact, you often carry out commands like that without creatin g a command object, although 
you can create a command object if you want, and you can make the command undoable.) . 


A mouse command object has the responsibility to track the mouse and provide appropriate 
feedback to the user while the mouse button is down. If the mouse action changes the 
document, the command object is also responsible for doing, undoing, and redoing the 
command. 


Because there is only one level of undo (that is, only the most recent command can be 
undone) there is generally only one command object, and at most two, ata time. There can 
be two command objects in only two cases: when a new command object has just been 
created and the old one has not yet been committed and freed; and when there is a new 
command that does not change the document, for example, when the user makes a 
selection. When the user makes a selection, the last command should remain undoable, 
and therefore the last command object remains in existence. MacApp maintains the last 
command for you, and calls Dolt, Undolt, and Redolt when appropriate. 


Where it fits in 


Command objects, along with view objects, form the heart of any Macintosh application. 
Without view objects, the user could not see what a document contains; without command 
objects, the user could not select and change what a document contains. (Actually, if your 
application does not use the mouse inside views and if none of your commands can be 
undone, you don’t need to deal with command objects, but that would violate the 
Macintosh user interface standards.) 


Command objects are created by other objects, generally to change themselves. For 


example, when the user types, the document object may create a command object to add the 
new data to its set. 


TPrintHandler 


TPrintHandler is provided to define a common set of methods for printing that can be called 
by other MacApp objects. 


TPrintHandler is a descendant of TEvtHandler: 


What it does 


Every view has a print handler field. If the view can be printed, you install a print handler 
object in that field after you create the view. When the user chooses printing commands 
from the File menu (or prints from the Finder), the commands are directed to the print 
handler. 


Where it fits in 
TPrintHandler defines the interface for printing for all MacApp applications, but the 


methods of TPrintHandler generally do nothing. The unit UPrintin g defines a descendant 
of TPrintHandler, TStdPrintHandler, which provides enough printing capability for most 
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applications. Some applications customize TPrintHandler (or TStdPrintHandler) to provide 
nonstandatd (or additional) printing features. 


TDeskScrap View 


TDeskScrapView provides a mechanism for viewing the desk scrap from a MacApp 
application. The desk scrap is the mechanism the Macintosh system provides for 
exchanging data between applications. When information is cut or copied, an application 
places it in the application’s Clipboard, generally in the same form as the application’s other 
data. When the user leaves the application (by quitting, using Switcher™, or invoking a 
desk accessory) the information in the Clipboard is converted to one or both of two data 
formats common to all Macintosh applications:. PICT data, which is a QuickDraw picture, 
or TEXT data, which is a simple series of ASCII characters. In addition, the application 
often writes data to the desk scrap in its own format. 


When a MacApp application starts up or the user returns to the application after an 
excursion to a desk accessory or another Switcher partition where a cut or copy may have 
occurred, MacApp creates a desk scrap view object to show the common-format data in the 
desk scrap. (The application gets a chance to claim the Clipboard for itself so it can display 
the desk scrap data in a different way.) 


TDeskScrapView is an immediate descendant of TView. 


What it does 


When the application starts up, MacApp creates a desk scrap view object. (Your 
application gets a chance to create its own kind of object to display the desk scrap data.) 
When the Clipboard is about to be displayed, that object reads the contents of the desk 
scrap and displays it in the Clipboard window. The desk scrap view handles the primary 
responsibility of any view: drawing the required area of the view when called. 


Where it fits in 


TDeskScrapView gives all MacApp applications a way to handle the desk scrap. Desk 
scrap data generally comes either in PICT or TEXT form, but applications also can, and 
often do, write data in a form preferred by the application in addition to the PICT or TEXT 
data. When your application starts or returns from an excursion to a desk accessory or 
another Switcher partition, you can check if there is data of your application’s format in the 
desk scrap. If there is, you can create a view of your own type that can read that data and 
display it. Otherwise, you can let MacApp create a desk scrap view. 


UPrinting 
This unit provides enough printing capability for most applications. 
UPrinting provides “standard” printing, really a set of printing capabilines. UPrinting can 


> handle the standard printing-related menu commands: Page Setup, Print, and Print 
One 
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e handle Undo and Redo for Page Setup 
e display page breaks on the screen when the user requests them 


e when printing is ordered, tell the view to draw itself, page-by-page, and direct the 
drawing to the printer 


e handle printing from the Finder 


TStdPrintHandler 


TStdPrintHandler implements standard printing, which is sufficient for most applications. 
This object type allows the user to set the starting page number, allows the user to set the 
margins, and prints page numbers. It puts up a Pause/Continue/Cancel dialog and handles 
cancellation. (Some of those capabilities come very easily; others require a bit of application 
code.) 


TStdPrintHandler is an immediate descendant of TPrintHandler. 


What it does 


Aside from handling the printing menu commands, TStdPrintHandler calculates page 
breaks, and does on-screen (or on-paper) page adornment. 


Where it fits in 


When you create a printable view, you install a print handler in a field of the view provided 
for the print handler. In the most common case, you include UPrinting in your application 
and create an instance of TStdPrintHandler that becomes the print handler for the view. 
When the user picks a printing command from the File menu, MacApp calls the appropriate 
methods of the view, and those methods call the methods of the print handler you have 
installed. The print handler tells your view to draw itself, as needed. 


TStdPrintHandler has “hooks” for more complex features, allowing you to put up a dialog 
to get a starting page number and set the margin and print page numbers. 
TPrintStyleChangeCommand 


This object type implements a command object for the actions associated with the Page 
Setup dialog box. It generally is of no interest to application programmers. 


What it does 
TPrintStyleChangeCommand creates an object that handles the results of the Page Setup 


dialog box. Creating a command object allows the user to undo and redo the Page Setup 
command. 
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Where it fits in 


A TStdPrintHandler object creates an object of this type when the user chooses the Page 
Setup command. 


UTEView 


UTEView implements simple text editing using the TextEdit routines of the Macintosh 
Toolbox. This unit allows you to take in text with up to 32767 characters; display the text 
using margins set by the program; edit the text with cutting, pasting, copying, and 
backspacing; move the insertion point with the mouse; select parts of the text using the 
standard Macintosh selection methods; and print the text as it appears in the view. In sum, 
this unit integrates the functions provided by TextEdit and provides enhancements. 


TTEView 


`- A text edit view is a view that can show text. TTEView offers the simplest form of text 
editing. The editing capabilities that MacApp supports for a text edit view are those 
provided by the Toolbox TextEdit routines. This kind of view can be used wherever those 
capabilities are sufficient. To implement more capability, you can customize TTE View or 
define a completely different descendant of TView. If you define your own immediate 
descendant of TView, you must override the same TView methods that TTEView 
overrides. 


TTEView is an immediate descendant of TView. 


What it does 


A text edit view can take in typing (key commands) and can handle the Cut, Copy, Paste, 
Undo, and Redo commands. It also takes care of selecting and deselecting text and moving 
the insertion point with the mouse and makes sure that text is displayed correctly during 
automatic scrolling. It can hold any number of characters up to 32,767. It handles 
pagination and can be printed. The mouse pointer is changed to an I-beam pointer when 
appropriate. The selection is scrolled into the visible part of the view when a command is 
done or undone. 


The text of a text edit view is some part (or all) of a document. When it is only part of a 
document, the text edit view is embedded in another view. In any case, your document 


object type does not have to implement text editing methods because the text editing 
methods are all implemented within TTEView. 


Where it fits in 


TTE View is used to implement simple editing. You can customize it to add any special 
features your program needs. 
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TTECommand 


TTECommand is used as an ancestor object type for TTECutCopyCommand, 
TTEPasteCommand, and ee eee TTECommand is an immediate 
descendant of TCommand. 


What it does 


TTECommand implements some methods and defines some fields that are common to 
TTECutCopyCommand, TTEPasteCommand, and TTETypingCommand. In particular, 
TTECommand contains fields to'record the state of the text before the command, so that 
Unda can restore the text to its original state. 


Normally, editing commands are associated with a document, not a view. However, a 
TTEView is responsible for holding document text while it is being editing and is therefore 
worked on by a TTECommand. 


Where it fits in 


This object type is instantiated for the Clear command. You may want to customize it to 
implement cut, copy, paste, or typing in a different way or to implement your own text 
commands. 


TTECutCopyCommand and TTEPasteCommand 


The text edit cut/copy command type implements the standard Edit menu Cut and Copy 
commands for text edit views. The text edit paste command type implements the standard 
Edit menu Paste command for text edit views. 


TTECutCopyCommand and TTEPasteCommand are immediate descendants of 
TTECommand. 


What they do 


A cut/copy command object is created when the user chooses the Cut or Copy command. If 
the user chooses Cut, the cut/copy command object removes the currently selected text and 

places it in the Clipboard. If the user chooses Copy, the currently selected text is copied to 
the Clipboard, but the selection is not changed. If the user chooses Paste, the paste 
command object places the contents of the Clipboard at the current insertion point or uses it 
to replace the current selection. Undo reverses the commands, and Redo carries out the 
command again. 


Where they fit in 


These commands automatically work as long as you are using a TTEView object or a 
descendant of TTEView. 
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TTETypingCommand 


The typing command object handles typing in a text edit view. 


TTETypingCommand is an immediate descendant of TTECommand. 


What it does 


A typing command object adds characters to the text edit record in response to typing and 
removes a character in response to a backspace. Undo removes the characters added by 
this command or restores characters removed with a backspace. One typing command 
stays in effect until a command of another type is given. Therefore, undoin g a single 
typing command can remove or restore any amount of text. 


Where it fits in 


When the user types on the keyboard when the selection is in a text edit view, a typing 
command object is created unless a typing command is already in progress, the selection 
has not changed since the last character was typed, and no command that changed the 
document was given. 


UDialog 


The dialog unit, UDialog, implements support for modal and modeless dialog boxes. A 
modal dialog is a dialog that requires a response before the user can continue. A 
modeless dialog acts like an ordinary window: the user can deactivate the dialog without 
answering and can later reactivate it. The Find dialog in MacWrite™ is an example of a 
modeless dialog. 


Dialogs appear in windows. The windows may or may not be scrollable and resizable and 
they may or may not have a close box. They generally have some default which occurs 
when the dialog is dismissed by pressing the Enter key or Return key. 


UDialog defines dialogs as groups of dialog items. An item can be a text box (which 
can take alphanumeric-only or numeric-only input and can validate what the user types) or a 
control such as a radio button. (Radio buttons are the small, round buttons you often see in 
Macintosh dialogs. They are always grouped into clusters, where one and only one 
member of the cluster can be selected: when the user selects a new button, the old selection 
is automatically deselected.) 


The items in a dialog are instances of descendants of TView. They are grouped together 
using a dialog view, which is a kind of concatenated view. A concatenated view is 
called a parent view and the items contained within it are its child views or children. 
UDialog defines an object type TCat View (for concatenated view) that is used as an 
ancestor type for TDialog View (dialog view). You can use TCatView for other purposes, 
if you wish. The children of a concatenated view can be views of any type that is 
descended from TView; they do not have to be dialog items. 


As with other views, dialog views appear in windows. UDialog defines a descendant of 
TWindow, TDialogWindow. 
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The object types defined in UDialog are TCatView, TDialog View, TKeyHandler, 
TNumberltem, TRadioCluster, and TDialog Window. These object types are not described 
further in this chapter. See Chapter 10 for full details. 
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Chapter 3 
Using MacApp 


The MacApp package consists of 
e UObject, the unit that defines the basic characteristics of objects. 


e UList, the unit that defines a dynamic array object type for use in MacApp and 
applications. i 


°- UMacApp, the unit that defines MacApp itself. 


* A number of “building block” units that can be used to add additional functions to 
your application: UPrinting, UTEView, and UDialog. (Because of the way MacApp 
is organized, other “building blocks” can be added at any time.) 


> Several build files that can be used to automate the process of compiling and linking 
MacApp, the sample applications, and your own applications. 


e A number of sample programs. 


Before using MacApp, you must install it on your disk. Most people then build one or 

more of the sample programs into working applications. Then, you can start working on 

your own application, either starting from scratch or by modifying one of the samples. 

This chapter begins with installation instructions, followed by build instructions, describes 

. the structure of a MacApp program, and, finally, describes the sample applications included 
in the package. 


Installing MacApp 


This section has instructions for installing MacApp’'on your hard disk. It assumes that you 
have MPW already installed. See the Macintosh Programmer's Workshop Reference for 
details on installing MPW. 


Follow these steps to install MacApp: 


1. Create a folder named MacApp in your MPW folder. (If you prefer to place it 
elsewhere or name it something else, you should modify the MacAppStartup file to 
accommodate this.) 


2. Copy the contents of all MacApp disks into your MacApp folder and put the disks in 
a safe place. 


3. Open the folder More MacApp Source Files and move the contents into the folder 
MacApp Source Files. There may also be a folder Still More MacApp Source Files. 
If there is, open that folder also and move its contents into MacApp Sources. You 
can now throw away the empty folders More MacApp Source Files and Still More 
MacApp Source Files. Do the same with any other folders with names of the form 
More... and Stll More. .:. 


4. Modify your UserStartUp file in the MPW folder to contain the line 


Set MacApp "(MPW}MacApp:" 
Export MacApp 
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execute "(MPW}MacApp:MacAppStartup"™ 


If you’ve placed the MacApp folder elsewhere, be sure to modify the MacAppStarmp 
file and the above lines appropriately. 


MacAppStartup defines a number of shell variables for MacApp which, among other 
functions, sets up MacApp to use HFS, the hierarchical file system. If you are using 
MEFS, the original “flat” Macintosh file system, such as is used with a Macintosh XL, 
use this line in your UserStartUp file in place of the third line just given: 


execute "(MPW}MacAppStartup.XL" 


If you are low on disk space, you can save space with these techniques. 


* Delete any fonts, desk accessories, print drivers, utilities, or other elements that you 
don’t need. 


e Don’t copy all the MacApp sample programs onto your disk. 
When the installation is done, you should be able to build one of the sample programs or 


one of your own MacApp programs. Refer to the section “Building a MacApp program,” 
below, for details on how to build a program. 


File-naming conventions 


MacApp file names follow several conventions: 
.© UAppName.p contains the Pascal interface for the unit named UAppName. 


¢ UAppName.incl.p, UAppName. inc2.p, and so on contain the implementation of the 
unit named UAppName. 


e UAppName.a contains supporting assembly source for the unit named UAppName, 
if any is needed. 


* MAppName.p contains the main program for the application named AppName. 
+ AppName.r contains the Rez input for the application named AppName. 


If additional units are requred, they are usually named UUnitName, and the files containing 
the interface and implementation of the unit follow the conventions given above. 


All the make files and USES staternents conform to these conventions. The documentation 
refers to particular files in several ways: 
e By filename; for example: UPrinting.p, UMacApp.inc2.p, and DrawShapes.r 


¢ By the unit name defined within the file; for example: UPrinting , UMacApp, 
UDrawShapes 


e By what the file is; for example: the printing unit, the MacApp module, and the 
DrawShapes program 


Therefore, the printing unit is defined as UPrinting and can be found in the files 
UPrinting.p and UPrinting. incl.p. If you use this unit, your USES list would contain the 
line: 


UPrinting, 


Final page 3-2 


MacApp Programmer’ s Guide Using MacApp 


reflecting both the name of the file and the name of the unit defined in the file. Similarly, 
the MacApp unit (named UMacApp) can be found in the files UMacApp.p, 
UMacApp.incl.p, UMacApp.inc2.p, and UMacApp.inc3.p. In addition, this unit uses 
some assembly-language routines that are contained in the file UMacApp.a. 


Building a MacApp program 


The MacApp build process uses the MPW tool Make along with a MacApp command file 
Build, which together help automate the sometimes complicated process of compiling and 
linking MacApp programs. - 


Note: You need to be familiar with the use of the MPW Shell to use these files. If 
there are any terms in this section that are not familiar, refer to the Macintosh 
Programmer's Workshop Reference. 


In addition to automating the process of building debugging and nondebugging versions of 
any application that uses MacApp, Build allows you to use the Optimize tool to optimize 
your code. Optimize performs optimizations on method tables, making object-oriented 
code smaller. 


Important: The MacApp debu gging facilites do not work properly with optimized code, 
sO you should only optimize code when debugging is tumed off. 

Build only compiles when necessary. For example, if you specify nodebug and MacApp 

has already been compiled without debugging, it is not recompiled; if MacApp has been 

compiled with debugging on, itis automatically recompiled. 


You must create a file AppName.make for your application. Make files are provided for 
the sample applications. See “Creating a make file,” below for instructions for writing one. 
If you want to build a sample program or you already have a make file, see “Using Build,” 
below. 


The file MacApp.make is used when you want to build just the MacApp library. The form 
‘of this command is 


build MacApp 

This compiles all the MacApp units, UObject, UList, UMacApp, UPrinting, UDialog, and 
UTEView and combines them in the file MacAppLib.o. You may specify debug or 
nodebug when you build MacApp; opt will be ignored, as it only applies when linking an 
application. 

Creating a make file 

Every program built with Build must have a make file with a name of the form 


` AppName.make 


where AppName is the name of the application. In this file, you specify the application 
name, signature, and what files your application depends on. 
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The file Application.make is included in the MacApp release and is a template for your 
program’s make file. Most of the file is simply a set of assignments to Make variables. 
(Make is the MPW tool that is used to automate the build process.) The variables are: 


AppName = the name of the application 
Creator = the application signature 
NeededSysLibs =a list of required system libraries 


BuildingBlockIntf = a list of the building block interface files the application uses 
BuildBlockObjs =a list of the building block object files the application links with 
OtherInterfaces =a list of other Pascal interfaces that the application uses 
OtherLinkFiles =a list of other object files that the application links with 
OtherSegMappings =a list of -sn commands for the linker 


OtherRezFiles =a list of .r files that must be included in the Rez command, other 
than AppName.r 
OtherRsrcFiles = a list of resource files that are included by one of your Rez files, 


other than the Debug.rsrc and MacApp.rsre files 
See the make files for the sample programs if you need additional guidance. 
If you need to specify any additional files (such as assembly language files) that need to be 
linked with your application, you must provide dependency mules for them in your make 
file. For example, 
OtherLinkFiles = MyApp.a.o 


MyApp.a.o f MyApp.a FooInclude.a 


You do not need to specify build rules for Pascal compiles or MPW assemblies because 
they are covered by the default rules specified in MacApp.makel. 


The Build command file calls Make with your make file concatenated with the MacApp 
make files. The ordering is MacApp.makel, AppName.make, MacAp.make2, and 


MacApp.make3, When running Build with optimization on, MacApp.make2 is replaced by 
MacApp.opt.make2. 


Using Build 
For program AppName, the command line for executing a build is 


Build AppName 


Debugging is turned on by default (that is, debugging code is compiled in), although you 


can give the keyword debug after AppName, if you want. To build program AppName 
without debugging, use the command line : í 


Build AppName nodebug 
To build an optimized version of program AppName, use the command line 
Build AppName opt 


The opt keyword also implies nodebug. 
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MacApp Rez files 


In order to build a MacApp application, there are some resources you have to have in your 
Rez (the MPW resource compiler) input file. These elements are 


* MacApp Include files. See the “Include files” section below. 


e An Include line for your code. See the sample programs’ resource files for examples. 


e cmmu resource for your menus. See the “The cmnu resource type” section below. 

e An MBAR resource. See the “MBAR resources” section below. 

e An About application dialog. See the sample programs' resource files for examples. 
For complete examples of any of these elements, look at the Rez files of the sample 
programs. 


Include files 


Most of the “standard” MacApp resources are supplied as precompiled .rsre files. You 
include them with lines of the form 


include FileName.rsre 


If you don’t need all the standard resources, you can make copies of the files and remove 
the resources you don’t want. 


Some resources required by MacApp must be in your Rez input file. These include any 
cmnu or MENU resources you use. Look at the sample programs for guidance. ` 


The cmnu resource type 


The cmnu resource type is provided so that menus can be handled by MacApp in its own 
way. 


You define resources as type cmnu instead of MENU. These have the same syntax as 
resources of type MENU, except that menu items have one additional component, a 
command number (or the symbol nocommand). After Tunning Rez, the Make file runs the 
tool PostRez, which will generate the usual MENU resources, plus a single resource of 
type mntb and ID 0 which maps all command numbers for all cmnu resources encountered 
in the file into their corresponding menu and item numbers. 


The Rez command line must specify the file 

(MacApp} (RezMacApp }MacApp.r 

in order to define the template for cmnu resources. 
Note: Because the PostRez tool changes cmnu resources to MENU resources and other 
information MacApp needs to handle menus properly, you cannot use DeRez to 


decompile resources for MacApp programs. In addition, you cannot use the resource 
editor to change menu resources, because that will not provide all the information 
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MacApp needs. If you need to change your resources, you must edit the original 
resource file and allow Build to run Rez and PostRez again. 


MBAR resources 
MacApp requires one or two MBAR resources that tell it what to do with your menus. 


You must have an MBAR resource with ID 128. This resource gives the IDs of all menus 
that should be read in and displayed initially. MacApp looks for this resource when it starts 
up and loads all menus whose IDs are listed here. 


You can also have an MBAR resource with ID 129. This resource gives the IDs of menus 
that can be added to or removed from the menu bar by your application. The menus listed 
here are read in by MacApp but are not initially displayed. 


You can also have menus that are not listed in either MBAR resource. Examples of these 
are 


e` Buzzword menus, which contain strings meant to be placed in other menus under 
certain conditions 


°. The Debug menu, which has ID 900 and is treated as a special case by MacApp so 
that it is only read in if debugging code is included in the application 


e Non-standard menus such as graphical menus. These must have IDs over 
mLastMenu (which is 63). You need to handle these menus by calling the Menu 
Manager directly. - 


Menus handled by MacApp must have IDs from 1 to mLastMenu, regardless of which 
MBAR resource refers to them. 


Important: You should not use programmatically created menus; that is, your resource 
file should contain at least the menu title of every menu. 


The structure of a MacApp program 


MacApp programs are written with a certain structure. Some elements are mandated by the 
syntax, and are so identified here, and others are simply conventions that make it easier to 
maintain the programs. 


The elements of a MacApp program are the main program, the unit interface, and the unit 
implementation. Each element is generally kept in a separate file, although you can 
combine them, if you wish. See the sample programs for some further detail on these files. 
(In particular, MacApp includes debugging features which require the use of some compiler 
switches.) 


The main program, usually named MAppName.p, is generally very simple and small. A 
MacApp main program follows this structure: 


PROGRAM YourName; 
USES 
{units used by this program. } 
VAR 
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gYourApplication: TYourApplication; {The application object} 
BEGIN . 
InitToolBox({number of master pointer blocks to allocate}):; 
InitPrinting; {Only if you are using UPrinting} 
InitUDialog; {Only if you are using UDialog} 
New (gYourApplication); {Allocate the application object} 
gYourApplication.IApplication; {Initialize the application} 
- gYourApplication.Run; {Run the application} 
END. 


The rest of the application is generally run from the application’s Run method. The basic 
type TApplication is defined for you by MacApp, and you customize it in one of the units, 
creating your application type, called TYourA pplication here. That unit is listed in the 
USES declaration along with any other units needed to compile its interface. 


The unit interface file, usually called UAppName.p, defines the object types used by the 
program. The methods of object types must be declared in the style of aFORWARD 
declaration (although you never use the reserved word FORWARD). Where you want to 
reimplement an inherited method, you write the full interface for the method and follow it 
with the OVERRIDE reserved word. A unit interface file usually follows this structure: 


UNIT UnitName; 
INTERFACE 


USES 
{Any units used by the unit} 


CONST : 
{Any constants for the application} 


TYPE 
{Ordinary type declarations} 
{Object type declarations} 


IMPLEMENTATION 
{$I name of implementation file} 


END. 


*The unit implementation file, usually named UAppName.inc.p, can begin with a VAR part 
that declares any global variables for the unit followed by the implementations of the 
methods. You can, optionally, repeat the full interface declaration with the implementation 
of each method. There is nothing special about the design of this file; it consists simply of 
the global variable declarations, private constructs and type declarations, and the method 
implementations, which look like procedure and function declarations. 


If an application is large, it can be broken up ‘into a number of units. 


MacApp sample programs 


The MacApp package includes eleven sample programs that demonstrate how a MacApp 
program can be written. You can also use these programs to verify that MacApp is 
correctly installed on your system. 
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In using and examining these programs, you should be aware that their design is often 
dictated by the need to demonstrate features, and not necessarily by efficient programming. 
Use the sample programs as a starting place. 


You can build these sample programs with the MPW command lines 


Directory "{MacApp}Samples:programName sample:" 
Build programName 


See “Building a MacApp program,” above, for an explanation of the Build. 


All of the programs support windows that the user can move, resize, and scroll; multiple 
documents (except for DemoDialog, which uses no documents); desk accessories; display 
of the Clipboard; and other features of the user interface standard that MacApp delivers 
automatically. The features of each program are outlined below. 


Cards 


This is a program that demonstrates how to implement disk-based documents using 
MacApp. It is a simple, index-card-style database. 


Conference 


This is a simple conferencing program that sends and receives messages over AppleTalk. 
It illustrates the use of TTEView, TCatView (three text edit views are pieced together to 
form a parent view), and UAppleTalk. It also has a window which does not belong to any 
document. 


Important. The UAppleTalk unit, a building block that implements communication with 
an AppleTalk network, is not documented in this manual because it is considered 
preliminary. It is, however, included in the MacApp package. If you need to use it, 
examine the source file and the Conference program. 


DemoDialogs 


This is a sample program with no documents. It is used to illustrate uses of the UDialog 
building block. It has a Dialogs menu which allows the user to put up any of four sample 
dialogs—two modal dialogs, one scrollable modeless dialog, and one nonscrollable 
modeless dialog. 


DemoText 


This program is used to demonstrate the possibilities of the TEView building block. In 
addition to the capabilities of the SmallEditor sample program, it allows the user to specify 
font, style, and size for each document independently (all these commands are undoable); 
it allows the user to choose among all the possible view sizeDeterminer options; and it 
supports centering and left and right justification of text. The Font and Style menus are 
properly dealt with, including the display of “real” font sizes in outline style. The 
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TCommand. descendants used to alter font characteristics may prove to be useful 
prototypes. DemoText also supports printing and filing. 


DrawShapes 


In addition to menu commands (Shades) and mouse commands (draw shape, drag one or 
more shapes, select shapes) this program supports the Cut and Paste commands and 
variable-size document files, saves information in both the data fork and the resource fork 
of its disk files, has a command only accessible through use of a Command-key 
combination (Command-D, which puts up a special debugging menu or takes it down if it’s 
already up), and has a window divided into a palette frame and a main frame. 


Note: DrawShapes is a derivative of the Draw program that accompanied various early 
prerelease versions of MacApp. 


Flow 


The Flow program was written as a utility program to produce originals of the flow charts 
used in Chapter 7 of this manual. It is a script-based graphics program. 


Flow can display two different views of its data. The first view is the script. The scripr, 
which can be edited, consists of a series of lines. Each line defines a title or a box with a 
title. The chart view shows the flow chart defined by the script. The flow chart consists of 
a title followed by boxes that may be of several types and that may contain other boxes. 
The boxes generally contain text. They may be identified with numbers enclosed in circles. 


In the scripts, keywords are used to distinguish between the different kinds of boxes. The 
keywords also determine the placement of the titles within the boxes. The keywords are 
listed in the Keywords menu, and you can place a keyword in the script by choosing it 
from the menu or by typing it. (If you type it, you must use all uppercase.) For a keyword 
to work, it must be preceded by nothing but spaces. The effect of each keyword is as 
follows: 


* LOOP creates a rectangle with the text left-justified. 
* CALL creates a rounded-cormer rectangle with the text centered. 
e CALL2 creates a rectangle with double lines on the side. 
* TITLE centers the text over the following boxes, with no surrounding box 
e When there is no keyword, the text is centered in a plain rectangle. 
The keyword is normally followed by a string of text, terminated by areturn. In each case, 


the text is printed on the first line of the box only. The box is made just big enou gh to 
enclose what it contains. 


You can append an asterisk to any of these keywords, When there is an asterisk, the text in 
the box is printed in boldface type. 


If you end the script line with a number sign (#) and a number from 0 to 999, the number 
appears to the right of the box, enclosed in a circle. 
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Script lines may be indented. When a script line is indented one space (or tab) more than 
the preceding line, its box is enclosed within the box produced by the preceding line. If the 
following line is also indented the same amount, it is also enclosed in that box. It is an 
error to have a line indented more than one space more than the preceding line. When two 
script lines are indented the same amount, the boxes they produce are connected with a 
vertical line. 


The program has some additional menu commands. One allows you to add shadows to the 
boxes. Another allows you to save the chart as a PICT file, which can be read by 
MacDraw. 


Nothing 


This is a minimal application, consisting of five methods. Documents belonging to this 
application show windows that have a simple design displayed within them. This includes 
no application-specific menu or mouse commands. Printing and filing are supported (but 
the files only contain the current printing info, since there is no application-specific 
information to store). . 


OneBox 


This program displays a single, ornate rectangle in the window. Two kinds of actions are 
possible with this box: moving it around by dragging it with the mouse and changing its _ 
“shade” by selecting a shade from a menu. This program illustrates mouse commands and 
menu commands with full Undo features. It also illustrates how you can scroll the 
selection into the frame. In addition, it saves the window state (window size, window 
location on screen, and state of scrolling) in the document file and restores the window 
state when the file is opened. It supports printing using UPrinting. l 


Puzzle 


This program presents a version of the Puzzle desk accessory game that comes with the 
Macintosh. Each document has three windows. The main window is always visible when 
its document is open. The other two windows can be shown or hidden by user command. 
Puzzle supports printing and illustrates the complexities that arise when a document has 
more than one printable view. Window states for all three windows are saved in the 
document files. Puzzle includes undoable menu commands and undoable mouse 
commands, and these remain undoable when a different window belonging to the same. 
document is activated. Puzzle-scramble commands can be issued and undone no matter 
which of the three windows is active. Puzzle-move commands can be initiated from either 
of two of the windows, with a quite different user interface in each. 


SmallEditor 
This is a minimal but useful application. It includes editing of text within windows, 


saving and restoring of documents, printing, cutting and pasting of TEXT-type data, and 
full undo features. It is similar in function to the sample application included with MPW. 
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TwoDocKinds 


Using MacApp 


This program illustrates how to Support more than one kind of TDocument descendant in 
the same application. It was constructed by pasting together the SmallEditor and the 
OneBox sample programs, adding only what was absolutely necessary to make the two 
work concurrently. Box documents created with this program can be used by OneBox 
and vice versa, and text documents can be interchan ged with those from SmaliEditor, 
DemoText, and other text-handling applications. 


List of Features 


All of the sample programs have the standard characteristics common to all MacApp 
Programs, so those features, such as windows, menus, and saving and restoring 
documents are not included in this list. See the Nothing program for a sample that 
implements only those features and nothing else, 


Note: TwoDocKinds has all the features illustrated by both SmallEditor and OneBox, 
because it was constructed by merging those two applications. In addition, 
TwoDocKinds illustrates having more than one document type per application. 


Add and delete entire menus 
dynamically 


Command-key command not in menu bar 


Constrain a window so that it 
only grows in one direction 


Create descendants of TTEView 


Create PICT-type desk scrap data 


Cut and Paste (of an application-specific 
type) 


Cut and Paste (of text) 


Disk-based documents 
Filtered commands 
Font changes 

Font size changes 


Font style changes 


Mouse-tracking commands 


Final 


DrawShapes 
DrawShapes 


Puzzle (its Table window) 


Cards 
Conference 


DrawShapes 


DrawShapes 
Cards 
Conference 
DemoText 
SmallEditor 
TwoDocKinds 
Cards 


DrawShapes 
Cards 


DemoText 


DrawShapes 
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OneBox 
TwoDocKinds 

More than one document type 

per application TwoDocKinds 

More than one window per document 

(with menu commands to show 

and hide windows) Puzzle 

Multiframe window 

(created with NewPalette Window) DrawShapes 
Conference 

No documents DemoDialogs 

Save data in data fork of disk files All except DemoDialogs 

Save data in resource fork of disk files DrawShapes 

Save display state in document file DrawShapes 
OneBox 
Puzzle (saves state of all three windows) 

Two different views of the same data Flow 

Puzzle 

Undoable menu commands Cards 
DemoText 
DrawShapes 
OneBox 
Puzzle 
TwoDocKinds 

Undoable mouse commands DrawShapes 
OneBox 
Puzzle 
TwoDocKinds 

Use of UAppleTalk Conference 

Use of UDialog (modeless dialogs) DemoDialogs 
Puzzle 

Use of UDialog (modal dialogs) DemoDialog 

Use of UDialog 

(TCatView concatenated views) Conference 

Use of UList Cards 
DrawShapes 

Use of UPrinting Cards 
Conference 
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Use of UTEView 


Variable view size 


View-size determiner changes 


Window without a document 


Final 


Using MacApp 


DemoText 
DrawShapes 
OneBox 
SmallEditor 


Cards 
Conference 
DemoText 
SmallEditor 
TwoDocKinds 


DrawShapes 
(also the text examples, using inherited behaviour) 


DemoText 


Conference 
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Chapter 4 
Drawing 


Drawing in a MacApp application is different from drawin g in an ordinary Macintosh 
application. The calls that do the actual drawing are the same; what is different is the 
conceptual environment in which the drawin g occurs. 


This chapter begins by describing the basic sequence of events that results in images 
appearing on the screen or on paper. It includes a summary of the conceptual framework 
of QuickDraw, followed by a description of the conceptual framework of drawin gin 
MacApp. 


Note: QuickDraw is the library of routines that do drawing on the Macintosh. See 
Inside Macintosh for complete information. 


All that is said about drawing on the screen in MacApp applies to drawing to a page that is 
to be printed. MacApp is organized so that you don’t have to worry about the destination 
of your drawing. 


How MacApp applications draw 


MacApp programs never draw in “screen space.” Instead, they draw in “view space.” A 
view—an object of type TView (usually of a type that is a descendant of TView)—is an 
arbitrarily sized two-dimensional drawing surface. Typically, only part of the view is . 
visible in a window. The coordinate system of the view and the window may differ. 
MacApp automatically shows the proper part of the view in the window, so it appears that 
the window moves over the view as the user manipulates the scroll bars and the mouse and 
gives commands. The relationship between the view and the window and the 
characteristics of the window and view (size, coordinate system, and so on) can change 
under program control, generally in response to user actions. 


One of the primary differences between writing a MacApp application and writing an 
ordinary Macintosh application is that MacApp maintains the window illusion for you. 
You do not have to worry about what happens outside your view—your only 
responsibilities are to draw your view when MacApp tells you to and to Carry out your 
application’s commands. Other on-screen elements—the mouse pointer, the menu bars, 
and window borders—-are handled by MacApp. 


To summarize: The only drawing you need to do in a MacApp program is the drawing of 
your view, and the view is a two-dimensional surface of arbitrary size and coordinates 
whose relation to the screen or printed page is determined by MacApp, the user, and your 
application. 
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QuickDraw graphics concepts 


QuickDraw defines the drawing environment that is at the base of all drawing on the 
Macintosh. The QuickDraw drawing environment is based on a number of concepts, the 
most important of which are bit images, bit maps, and grafPorts. 


Those concepts are obscured in MacApp applications because MacApp mediates between 
your application and the display. QuickDraw concepts are described in the QuickDraw 
chapter of Inside Macintosh. The most important concepts are summarized in this section 
so that the discussion of MacApp concepts that follows is clear. 


Note: As well as defining the Macintosh drawing environment, QuickDraw defines 
a large number of drawing routines. This chapter does not deal with the drawing 
routines; they are fairly straightforward, and you can read about them in the 
QuickDraw chapter of Inside Macintosh. You use those drawing routines in 
MacApp applications just as you use them in any application. 


Bit images and bit maps 


The ultimate destination of all drawing on the Macintosh is a bit image. A bit image is 
simply a string of bits in memory that represents a rectangular display area. The screen and 
a page destined for the printer are examples of bit images. A bit map (type BitMap) is a 
data structure that points to a bit image. Bit maps have a bounds field, which is a rectangle 
that indicates what portion of the bit image is covered by the bit map. The bounds field 
also defines the coordinates of the upper left corner of the bit image, and therefore the 
coordinates of every other point in the bit image. 


Any coordinate system can extend for -32,768 to 32,767 points in the horizontal and 
vertical dimensions. (View coordinates have different limits, however.) Coordinates are 
expressed as a pair of numbers; the first coordinate in the pair is the horizontal coordinate, 
the second, the vertical. Horizontal coordinates increase as you move from left to right, 
and vertical coordinates increase as you move from top to bottom. 


More than one bit map can point to the same bit image, but they all share the same origin: 
the top left corner of the bit image. Each of the bit maps pointing to the same bit image can 
impose a different coordinate system on it. 


The coordinate system of a bit map is determined by the coordinates specified for the top 

left corner of the bounds rectangle. Because the top left corner is always the first bit in the 
bit image, the coordinates of all the bits in the bit image follow automatically from the 
coordinates of the top left corner. The bottom right corner of the bounds rectangle indicates 
the size of the rectangle. 


GrafPorts 


A grafPort is a complete drawing environment that defines where and in what way graphic 
operations will take place. An example of a grafPort is a window. 


In a sense, a grafPort is a “virtual display.” Each grafPort has fields that define 
environmental characteristics, such as the pen pattern, location, style, and mode. 
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GrafPorts also have a portBits field that is a bit map that points to the bit image this 
grafPort can draw in. When a grafPort is a window, the bit image pointed to by portBits is 
the screen. 


More than one grafPort can point to the same bit image; for example, more than one ~ 
window can be on the screen at the same time. 


Windows, though, do not typically occupy the entire screen, and do not typically have the 
same top left corner as the screen, or as each other. Each grafPort has a portRect field, a 
rectangle that specifies what subset of the bit image (more properly, what subset of the bit 


map) the grafPort can draw in. _ 


The portRect is specified in the coordinate system of the portBits bit map, which, in the 
case of a window, is the coordinate system of the screen. In the case of a window, the 
portRect is the content region of the window, which includes the scroil bars and the size 
box but not the title bar or the border of the window. When the window is moved or 
resized, its portRect is updated accordingly. 


Note: The MacApp TFrame object type declares an fContentRect field. The 
fContentRect field does not include the scroll bars and the size box, which are 
included in the QuickDraw content region. 


Two other grafPort fields of interest here are the visRgn and the clipRgn. 


A region is an arbitrary part of coordinate space. A single region can have any shape and 
size, and it can be made up of any number of discontiguous parts. See the QuickDraw 
chapter of /nside Macintosh for more discussion of regions. MacApp usually uses 
rectangles instead of regions, because it is generally easier to handle rectangles in - 
programs. 


The visRgn is the part of a grafPort that’s actually visible. In the case of a window, it’s 
normally the part of the window that’s not covered by other windows. 


The clipRgn is the grafPort’s clipping region, an arbitrary region that can be used to further 
limit drawing to any region within the portRect. MacApp uses clipping regions to 
implement frames, as described below. 


The only part of the screen that your MacApp application needs to draw is the intersection 
of the portRect, the visRgn, and the clipRgn. MacApp uses a number of graphic concepts 
to mediate between your application and that part of the screen. Those concepts are 
discussed in the following section. 


When you draw in a grafPort, you draw in that grafPort’s coordinate system. By default, 
the origin is at the top left corner of the grafPort. The location of the origin, and therefore 
the coordinate system of the grafPort, can be changed with a call to SetOrigin. MacApp 
calls SetOrigin for you during its focusing operation. 


MacApp graphics concepts 


MacApp hides many of QuickDraw’s concepts from you. The key concepts for drawing in 
MacApp are the view and the frame; neither of these concepts corresponds exactly to a 
QuickDraw concept. 
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A view is a two-dimensional, rectangular, displayable representation of the data in a 
document, or of other information necessary for the use of the application. A view has a 
coordinate system defined by the field TView.fExtentRect, which defines the limits of the 
view in its own coordinate system. The size of the view can be changed by the program if 
the document grows larger or smaller. View coordinates must be non-negative and should 
not exceed 32,000 (32K minus 768). 


Frames and windows 


A view is really an imaginary, invisible construct. Part or all of a view can be shown on 
the screen in a frame. A frame is a rectangle on the screen. 


Frames can contain other frames. For example, a window is a frame that displays the 
borders and title bar that you see on the screen. The window contains at least one other 
frame, which shows some part of the document’s view. Documents can have several 
views, and several of those might be displayed in a single window or in several windows. 
Each view is displayed in a separate frame. Figure 4-1 shows a window that holds two 
frames, each of which shows a part of a different view. 


Figure 4-1 
A window with two frames 


views 





Frames usually have a variable location and size. Typically, MacApp maintains the size 
and location of frames in response to user actions, clipping your drawing to the edges of 
the frame so your view displays within the borders of the frame. . 


MacApp tells your view to draw itself when it creates or displays a frame or is preparing 
the view for printing. Your view is told what part of the view is actually showing in the 
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frame and therefore needs to be drawn. That area is the intersection of the portRect, the 
visRgn, and the clipRgn, as described under “MacApp graphics concepts,” above. (You 
don’t have to pay attention to that information; MacApp always clips to the borders of the 
frame.) In addition, you are told to redraw only the parts of the view that have chan ged. 


A window is an object of type TWindow, which is a descendant of TFrame. A window is 
a special case of a frame, with some extra properties of its own. 


A frame can have other frames within it; if it does, it is the container of the subframes 
within it. 


At the highest level of the frame hierarchy is a window, which has no container. 
Therefore, every frame (except a window) is in a window. 


draw except when MacApp tells it to. When you change something that alters the display, 
your application should tell MacApp that that part of the view is now invalid; later, when 
the view needs to be redrawn, MacApp tells the application to draw all the invalid parts. 


The location and size of each frame is defined by its frame.fContentRect field. The top left 
point of this rectangle defines the offset of the frame relative to the top left of its container, 
the bottom right point implicitly defines the extent of the rectangle. Both points are in the 
coordinate system of the container. 


Although windows are frames, they are different from other frames. For the rest of this 
discussion, windows are always called windows. The references to frames refer to frames 
other than windows: in other words, the word frame is used here to refer to a frame 
contained within a window. 


As windows. are created, MacApp calls the Window Manager to set up a grafPort for each 
one. A frame does not have a grafPort of its own, and must use the one belonging to the 
window it appears in. All drawing actually takes place in the portRect of the window, 
using the window’s coordinate system. However, you never have to know about the 
window’s coordinate system, because you always draw in your view, using the coordinate 
system of the view. The most important way that MacApp reconciles the two coordinate 
Systems is with a process called focusing. This is explained below. 


Printing 


Printing is also done through a gratPort. From your program’s perspective, printing is 
handled through print handlers and views, A print handler is created when the view is 
created. (It typically is of a type defined by the MacApp unit UPrinting.) The print handler 
divides the view into pages and asks your view to draw each page in tum. Your view 
usually has no need to consider whether drawing is destined for the printer or for the 
screen; the print handler simply asks for a certain area to be drawn in the same way 
MacApp asks your application to draw a certain area of the view for display in a frame. 


Important: If a view is to be printable on a Postscript printer such as the LaserWriter, 
you should avoid using regions, using transfer modes other than srcCopy for anything | 
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other than bitmaps, and inverting shapes. There are additional restrictions plus some 
performance considerations you may want to take into account. See the LaserWriter 
Reference for complete information. 


Focusing 


MacApp is able to allow you to draw in your view without regard to the part of the view 
displayed on the screen and the position of that displayed part thanks to a process called 
focusing, implemented by TFrame.Focus. Focusing sets up the grafPort so that when 
you draw in view coordinates your drawing appears in the proper frame on the screen. 
Focus has three main steps: 

e setting the current grafport 

e setting the origin 

e setting the clipRgn 


Setting the origin involves making a call to the QuickDraw routine SetOrigin. The 
coordinate system of the current grafPort is set to the coordinate system of the view. 


The clipRgn is then set to the intersection of the boundaries of the frame and the existing 
clipRgn, using the MacApp global procedure ClipFurtherTo, which calls the QuickDraw 
routine SetClip. 


The end result is that clipping allows on-screen drawing only in the part of the view thar 
shows in the frame. 


TFrame.Focus is called frequently by MacApp and can be called by your application before 
making calls to QuickDraw or before invalidating part of a view. 


MacApp automatically focuses on the view’s frame before calling any of the following 
` methods: 

Object Methods 

View Activate, Draw, DrawBreaks, HighlightSelection 

Command TrackFeedback, TrackMouse 

Frame DoTrackControl, DrawInterior, DrawView 
MacApp also focuses for you when you call TView.InvalidRect and TFrame.InvalidRect. 
You need to call Focus before making any QuickDraw calls or invalidating with other 
methods, including the view methods DoMenuCommand, DoMouseCommand, and 


DoKeyCommand, and the command methods Dolt, Redolt, and Undolt. (Note that 
drawing in those methods is rare, but invalidating is common.) 


Updating 
Updating is the process of redrawing the contents of a window when its previous contents 


are invalid. A window is not necessarily redrawn immediately every time something in it 
changes. Rather, the Window Manager keeps track of the region that needs to be updated 
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(the update region), and issues an update event when the update region isn’t empty. The 
update event is normally processed after all other events (update events have the lowest 
priority). (See the Event Manager chapter of Inside Macintosh for a discussion of event 
priority.) 


In MacApp, even though some events (such as scrollin g) affect only a single frame, the 
Window Manager can issue an update event only for the entire window. If the update 
region is restricted to a single frame, then MacApp only tells the view looked on by thar 
frame to draw itself. 


The detailed steps for an update event are shown in Chapter 7; here is a brief summary. To 
use MacApp, it is very important that you understand these steps. 


Whenever your application, MacApp, or any component of the Toolbox or operating 
system Calls one of the Window Manager routines InvalRect or InvalRgn, the specified 
rectangle or region is accumulated into the update region, and the Window Manager issues 
an update event. (MacApp applications usually call TFrame.InvalidRect or 
TView.InvalidRect to invalidate.) The next time through the event loop, when there are no 
other events pending, the Event Manager issues an update event, which is then is 
intercepted by MacApp. 


When MacApp first gets the update event, it calls the Window Manager procedure 
BeginUpdate, which replaces the window’s visRgn by its intersection with the update 
region, to ensure that nothing is redrawn unnecessarily. (As you recall, the only part of the 
screen that is actually redrawn is the intersection of the portRect, the visRgn, and the 
clipRgn.) 


MacApp then erases the update region and calls the method TFrame.DrawAll for each 
affected frame to redraw the window. This method calls itself recursively to draw every 
subframe in the window. For each frame, DrawAll focuses on the frame, to set up the 
coordinate system in view coordinates and to restrict the clipRgn to the boundaries of the 
frame. It then calls your view’s Draw method to draw the contents of the frame. DrawAll 
passes the rectangle, in view coordinates, that needs to be drawn to your Draw method. 
DrawAll also calls the view methods that highlight the selection and draw any adomments 
such as page breaks. 


Finally, MacApp calls EndU pdate to restore the visRgn to the way it was before the call to 
BeginUpdate. 


Scrolling 


Scrolling means moving a frame around over a view. When MacApp receives a scrolling 
event for a frame, it recalculates the view coordinates of the frame and invalidates the part 
of the view that scrolled into the frame. 


When MacApp determines that a scrolling event has taken place, the first thing it must 
calculate is how far to scroll the frame. For the sake of simplicity, this discussion assumes 
vertical scrolling. The location of the elevator within the scroll bar, which is maintained by 
the Control Manager, is used to keep track of the scroll position of the frame. 


If the user has clicked in a scroll arrow or in the gray area above or below the elevator, then 
the view is to be scrolled by a fixed amount. If the user holds the mouse button down, 
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then MacApp continues to scroll by the same fixed amount. In either case, MacApp tells 
the Control Manager to adjust the setting of the elevator accordingly. 


If the user moves the elevator, then MacApp reads the setting of the elevator to determine 
how far to scroll. MacApp scrolls the view until the ratio between the scroll position and 
the length of the view is the same as the ratio between the elevator location and the length of 
the scroll bar. 


Having determined how far to scroll the view under the frame, MacApp redraws the 
contents of the frame in two steps: 
e It calls the QuickDraw procedure ScrollRect to shift pixels that remain in the frame. 
e It calls InvalRect to invalidate the rest of the frame (see “Updating,” above). 
If the frame is scrolled by less than its full length, part of the old contents will still show in 
. the frame, shifted by the amount the frame is scrolled. MacApp takes advantage of this fact 


by calling ScroliRect to shift that portion of the contents to its new location. Pixels that are 
scrolled out of the frame are discarded. 
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The Cookbook 


This chapter has instructions for producing a MacApp program. 


It is divided into 11 sections: documents, views, windows, handling mouse events, 
implementing standard edit commands, menus and commands, printing, using TEView, 
using UDialog, using the AppleTalk unit, supporting the clipboard, and error handling. 
Each section begins with recipes needed by every program, and goes on to show how to 
implement more specialized and sophisticated behavior. 
Every program needs to implement the parts discussed in at least these recipes: 

* “Creating a document” 

° “Initializing a document” 

° “Creating a view” 

e “Initializing a view” 

e “Drawing a view” 

e “Creating a vindow” 
In addition, for most applications you need to implement the parts discussed in these 
recipes: 

e Saving and restoring data 

° The Clipboard 

° All the recipes under “Standard editing commands” 

e Some recipes under “Menus and commands” 

e Some or all of the recipes under “Handing mouse events” 
When you implement an application with these ingredients, the application displays a 
standard window that may or may not have horizontal and vertical scroll bars, a size box, a 
close box, and the standard menus. The application can cut, copy, paste, undo, and save, 
and can open old and new documents. The application can handle any number of 
documents at a time, and its windows are refreshed correctly when necessary. The 
application can track the mouse when the mouse button is down and can act appropriately. 
Each recipe includes the following elements: 

* Purpose: an explanation of why you use this feature. 


* How to doit: step-by-step instructions for implementing this feature. These 
instructions often include object type or interface declaration samples and references 
to other recipes. 


* Template: listings of sample implementations or implementation frameworks for the 
major methods needed to implement the feature described in the recipe. 
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The word item is used in this chapter to indicate any basic data element of your program. 
For example, EachItemDo is.a method that you usually name according to the object type 
most basic to your data set. If your data set consists of different types of fruit, that method 
might be called EachFriitDo. Similarly, when an object is to be of some object type unique 
to your program, the type is called TItem in this chapter. 


As in the rest of this manual, the word Your is included in variable and type names that 
your application declares. Replace the name with some appropriate word. 


You can use the Nothing program, included in the Nothing Sample folder, as a base for 
your application. Nothing is.an application that has the standard Macintosh interface and 
nothing else. It can display windows with scroll bars, a size box, a close box, and a title 
bar, has the standard menus, refreshes the window correctly, can show the Clipboard, and 
allows the use of desk accessories, It can even save and restore documents, but the 
documents and the windows have nothing significant in them. (The window actually 
shows a fixed text string.) The Nothing program’s source consists of the following files: 


e MNothing.p, the main program 

e UNothing.p, the interface file 

e UNothing.incl.p, the implementation file 

e Nothing.r, the resource compiler input file 

e Nothing.make, the make file for building the program 


The last two files are used only in the Macintosh Programmer’s Workshop. If you are 
using a different development system you may have to.create your own files to perform the 
equivalent functions. ` 


If you begin with the Nothing program and modify it to create your application, you will 
make most changes either to the implementation file or to the interface file. In addition, 
same changes are made to the resource compiler input file. The main program is rarely 
changed. Many of the methods described in the basic recipes in this chapter are included in 
the Nothing program, because they must exist so that the Nothing application can run; you 
must modify those methods to do tasks specific to your application. 


If you have a large program, you may want to break the implementation unit into two or 
more files, or even to add additional units. In addition, you may want to break your object 
program into segments. See the Segment Loader chapter of Inside Macintosh for 
information on segmenting your program. 
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Documents 


Creating a document 


Purpose 


A document controls the data set of your application independently of how it is displayed or 
printed. : 

MacApp asks your application to create a new document when the user chooses the New - 
command from the File menu and when the user opens the application’s icon. 


See the “Creating a new document” and “Open an old document from a menu” sections in 
Chapter 7 to see what happens when a document object is needed. 


How to do it- 


1. Declare the file type for your document. The file type is generally stored as a constant 
yourFileType, and is always a four-character string, 


If you use an existing file format, use the predefined file type. A file made up of strings of 
characters, where each line or paragraph is terminated by a return, is of type TEXT. A file 
consisting of QuickDraw pictures is of type PICT. 


If you have your own file format, the file type is an arbitrary four-character string. File 
types should be registered with Developer Technical Support to ensure that they are and 
remain unique. To register your types, write to 


Developer Technical Support 
Department 5729 

Apple Computer, Inc. 

20525 Mariani Avenue 
Cupertino, CA 95014 


2. Implement TYourA pplication. DoMakeDocument. MacApp calls 
TYourA pplication. DoMakeDocument when a new document needs to be created. You 
need the following declaration as part of the definition of TYourA pplication: 


FUNCTION TYourApplication.DoMakeDocument (itsCmdNumber: INTEGER) : 
TDocument; OVERRIDE; 


A sample implementation is given in the template for this recipe. 

The command number is primarily used for applications with more than one document 
type. If your application provides more than one document type that the user can choose 
from a menu, use the command number to determine which type of document to create. 


3. For each document type, implement TYourDocument, as described in the “Initializing a 
document” recipe. TYourA pplication. DoMakeDocument should call TYourDocument. 
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4. For each document type, if you have menu commands other than the standard File menu 
commands (New, Open, Save, Save As, Save Copy, Revert) that apply to the document or 
its contents (regardless of which window is active or which view is selected), override 
TDocument.DoMenuCommand. See the “Creating menu commands” recipe for details on 
DoMenuCommand. 


Template 


FUNCTION TYourApplication.DoMakeDocument (itsCmdNumber: INTEGER) : 


a TDocument; 
VAR : 


aYourDocument: TYourDocument; 
BEGIN 
New (aYourDocument) ; 
FailNIL (aYourDocument) ; 
aYourDocument .ITYourDocument (yourFileType) ; 
DoMakeDocument := aYourDocument; 
END; . 
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Initializing a document 


Purpose 


After you create a new document you must initialize it, generally by calling 
TYourDocument. (The call is made from your DoMakeDocument method, described in the 
“Creating a document” recipe.) 


How to do it 


Implement TYourDocument. An example is shown in the template for this recipe. That 
template assumes you have a field fltemList, which is a TList-type object that stores your 
data. If your data is organized in another way, implement TYourDocument as appropriate, 


See the sample programs for more examples of this method. In particular, you may want 
to look at Puzzle and SmallEditor. 


Template 


PROCEDURE TYourDocument . lYourDocument (itsFileType) ; 
BEGIN 
IDocument (itsFileType, itsCreator, kUsesDataFork, NOT 
kUsesRsrceFork, NOT kDataOpen, NOT kRsrcOpen) ; 
{You may give different constant values in the above line. The 
values given are the most common commands, and indicate a document 
that uses only the data fork of the file and is not disk-based 
(that is, the entire file is copied into memory). See the Cards 
sample program for how to have a disk-based document. } 
fItemList := NewList; 
fSavePrintinfo := TRUE; {Used when saving the décument. Set to 
FALSE if you don’t want to save this. } 
{If you have a field or fields for the view or views, which you 
generally do, set it or them to NIL here. } 
END; 
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Saving and restoring data 


Purpose 


You save and restore data so that the user can save documents, open document icons, and 
open documents using the Open command and the standard file dialog box. In addition, 
you save the print state and the display state so that the user does not have to reestablish 
them each time the document is opened. 


See the “Save,” “Save As,” and “Open an old document from a menu” sections of Chapter 
7 for illustrations of what happens when the user opens or saves a document. 


How to do it 


Objects contain data and also have pointers to methods. You save only the data, not the 
method pointers, in your document file. The way you do that depends on how your 
application’s data is organized. 


This recipe assumes your data consists of a list of objects of a single type. In that case, 
` you generally create records that are equivalent to the data parts of the objects you want to 
save, and you save those records in the file. In the templates, the record type is called 
TFiledItem. When you want to restore that document file (that is, when the user opens that 
document), you create a new set of objects, reading data from the file and transferring it 
from the filed records to the objects. 


Important: Although, for simplicity, this recipe assumes that all the application’s 
objects are of one type, that is relatively unlikely. If your file contains several types of 
objects, you need to create a record type for each object type you want to save. In the 
file, each record should be preceded by a “kind” value that indicates what type of record 
follows. You first read the kind value, and then read a record of the type indicated by 
the kind value. You may read the record into a variable of the record type and then 
copy fields into the object, or if the field structure of the record and the object are 
identical, you can read directly into the object from the file. 


For this recipe, assume the following interface declarations: 


TItem = OBJECT (TObject) ; 
fKind: INTEGER; 
fDatal: DataTypel; 
fData2: DataType2; 
{any other fields} 


FUNCTION TItem.WriteTo(aRefNum: INTEGER): OsErr; 
FUNCTION TItem.ReadFrom(aRefNum: INTEGER): OsErr; 
{Other methods would normally be included. } 

END; 


1. Override TDocument.DoNeedDiskSpace. That method is called just before saving a 
document. It should return the total amount of disk space, in bytes, needed to store the 
data and resources for the document. Don’t worry about file overhead; MacApp adds that 
on. 


Final page 5-6 


MacApp Programmer's Guiide Cookbook 


MacApp uses the value returned by DoNeedDiskSpace to check if there is room on the disk 
to save the new file without first deleting the old. What happens if there isn’t enough room 
depends on the value of the document’s fSavelnPlace field. The possible values are: 


e sipNever to indicate that the original file should never be overwritten 


e sipAlways to indicate that the original file should always be overwritten when 
there is not enough space for a copy 


e sipAskUser to indicate that the user should be asked whether or not the 
original file should be overwritten when there is not enou gh space for a copy 


TDocument sets the value of fSavelnPlace in this way: 


IF NOT fDataOpen AND NOT fRsrcOpen THEN fSaveľnplace := sipAskUser 
ELSE fSaveInPlace := sipNever 


You can change the value of fSaveInPlace in your IYourDocument method. 


Take care that your DoNeedDiskSpace method returns the correct value or overestimates 
slightly; if DoNeedDiskSpace returns too large a value, the old file may be deleted 
unnecessarily, or DoNeedDiskSpace may erroneously inform the user that the file cannot 
be saved; if DoNeedDiskSpace returns too small a value, you may get an I/O error when 
the application tries to save the document, which could be particularly serious if MacApp 
has deleted the old file. 


The interface for this method is 


PROCEDURE TYourDocument .DoNeedDiskSpace (VAR dataForkBytes, 
rsrcForkBytes: LONGINT); OVERRIDE; 


A sample implementation is given in the templates for this section. It begins with a call to 
INHERITED DoNeedDiskSpace so MacApp can calculate the space needed to save the 
print state, the overhead for the file, and, if you are using the resource fork, the overhead 
for the resource fork. (You need to set document.fSavePrintInfo to TRUE in 
TYourDocument or TDocument.DoNeedDiskSpace won’t save the print state.) Notice that 
` method adds values to the initial values of dataForkBytes and rsrcForkBytes. MacApp sets 
the inital values of these parameters, and you should not reset them to 0. The rest of the 
implementation is very general, because the amount of space needed depends entirely on 
your application. See the sample programs for more specific examples. 


2. Override TDocument.DoWrite, called to write the document to a file. The interface for 
this method is 


PROCEDURE TYourDocument .DoWrite (aRefNum: INTEGER; makingCopy: BOOLEAN); 
OVERRIDE; 


A sample implementation is given in the templates for this section. 

The sample begins by saving the print state. MacApp does that for you when you call 
INHERITED DoWnte. (You need to set document.fSavePrintInfo to TRUE in 
TYourDocument or TDocument.DoNeedDiskSpace won’t save the print state.) Finally, the 
data is saved. 


The makingCopy parameter is primarily for disk-based documents. It indicates that 
DoWrite is being called to make a new copy of the file. 
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3. Override TDocument.DoRead, called when an existing document is opened. The 
interface for this method is 


PROCEDURE TYourDocument .DoRead({aRefNum: INTEGER; rsrcExists, 
forPrinting: BOOLEAN); OVERRIDE; 


The implementation is given in the templates for this section. The sample begins by 
restoring the print state if fSavePrintInfo is TRUE. Notice that the display state is not 
restored at this time. That is done when the window is created, with DoMake Windows. 


4. Assuming you have several different types of items, each a descendant of Titem and 
differentiated by a value that indicates the kind of item, add the following method to your 
document 


FUNCTION TYourDocument .MakeItem(kind: TItemKind): TItem; 
The implementation is given in the templates. 
You also need to define a set of constants for the different kinds of items. 


5. Give each object type in your document’s data set a WriteTo method for the 
TYourDocument. WriteTo method and a ReadFrom method for the 
TYourDocument.ReadFrom method. The interfaces for TItem.WriteTo and 
Tltem.ReadFrom are 


FUNCTION Titem.WriteTo(aRefNum: INTEGER): OsErr; 
FUNCTION Titem.ReadFrom(aRefNum: INTEGER): OsErr; 


The implementations are given in the templates for this section. 


If you have several different item types, each a descendant of Titem, assign a kind value to 
each of them, and create a method for each item type that returns the kind value for the 
item. Before you write each item’s data, write its kind value into the file. 


Templates 


PROCEDURE TYourDocument .DoNeedDiskSpace(VAR dataForkBytes, 
esrcForkBytes: LONGINT); 


PROCEDURE AddSize(item: TItem); 
BEGIN 
dataForkBytes := dataFforkBytes + {The number of bytes needed to 
Store the data in this item. 
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Don’t forget the kind value, 
if there is one.}; i 
END; 


BEGIN 
INHERITED DoNeedDiskSpace(dataForkBytes, rsrcForkBytes); 
{Get space needed to save print state} 
fItemList.Each (AddSize); {This assumes your data is stored in 
TList-type object in field 
TYourDocument .fItemList} 
{Add a value to rsrcForkBytes when you want to store some resources 
for the document. }. 
END; 


PROCEDURE TYourDocument .DoWrite(aRefNum: INTEGER; makingCopy: BOOLEAN) ; 


PROCEDURE WriteItem(item: TYourObject); 


BEGIN 
err := item.WriteTo(aRefNum) ; 
END; 
BEGIN 
INHERITED DoWrite(aRefNum, makingCopy); {Save print info record} 


fItemList .Each (WriteItem); 
END; 


PROCEDURE TYourDocument .DoRead(aRefNum: INTEGER; rsrcExists, 
forPrinting: BOOLEAN); 
{This method assumes you have a number of data object types, each a 
' descendant of TItem. The types are differentiated by a kind value.} 
VAR newItem: TItem; 
kind, i, nItems: INTEGER; 
size: LONGINT; 
BEGIN 
FailoOsErr (GetEOF (aRefNum, eof)}); {See the “Failure handling” recipe} 
INHERITED DoRead(aRefNum, fRsrcExists, forPrinting); {Read print 
info record} 
FailOSErr(GetFilePos(aRefNum, fPos)); 


nitems := (eof-fPos) DIV SIZEOF(TFiledItem) ; 
FOR i := 1 TO niItems DO i 
BEGIN 
size := 2; 
FailOSErr (FSRead(aRefNum, size, @kind)); 
newltem := MakeItem(kind); 
FailNiIL(newLtem) ; 


FailOSErr (newItem.ReadFrom(aRefNum)} ) ; 
fItemList.InsertLast (newltem) ; 
END; 

END; 


FUNCTION TYourDocument .MakeItem(kind: TItemKind): TItem; 
VAR firstTypeItem: TFirstItem; 
secondTypeItem: TSecondItem; 
BEGIN 
CASE kind OF 
kFirstType: 
BEGIN 
new (firstTypelItem) ; 
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MakeItem := firstTypelItem; 
END; 

kSecondType: 
BEGIN 
new (secondTypeltem) ; 
MakeItem := secondTypeltem; 
END; 

END; 

END; 


FUNCTION TItem.WriteTo(aRefNum: INTEGER): OSErr; 

BEGIN z 
{Here write the item’s kind and then the item’s data to the file. 
Return 0 or any nonzero error code in WriteTo. See the “Failure 
handling” recipe. } 

END; 


FUNCTION TiItem.ReadFrom(aRefNum: INTEGER): OSErr; 
{This method assumes your object has an IItem method that initializes 
the object. IItem loads the data fields with the data given in the 
parameter list. Note that fNextItem and fPreviousItem should be 
initialized to NIL so that TYourDocument.AddItem can work correctly. } 

VAR savediItem: TFilediItem; 

lengthOfFileditem: LONGINT; 

BEGIN 

lengthOfFiledItem := SIZEOF (TFiledItem) ; 

Titem( {parameters }) ; 

ReadFrom := FSRead(aRefNum, {length of this kind’s data}, @fDatal); 
END; 
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Purpose 

When opening an old document, the user usually likes to find the the window and view the 
way they were left when the document was saved, that is, with the window in the same 
position and with the same size and displaying the view in the same scroll position. This 
recipe shows how to implement that capability for a single window with one view. 


How to do it 


Each step in this recipe has some code in the template section. This recipe assumes that 
you only have one window per document. See the Puzzle sample program for an example 
of saving the states of-more than one window per document. 


1. You need a data type to save the state information. In the template, it is a record called 
DisplayState. Define this as a global data type, so you can refer to it in different methods. 


2. You need a place to save display-state data read from a document file and a BOOLEAN 
variable that indicates whether or not the display state has been read from a document file. 
In the template, both are fields of the document. The BOOLEAN field, fUseDisplayState is 

` set to FALSE for a new document. It is set to TRUE when a document is read from a file. 
When the document is read from a file, the saved display state is read and stored in 
fDisplayState. Otherwise, that field has no meaning. (Both fields are used only 
immediately after a document object is created.) 


3. In TYourDocument.[YourDocument, set f{UseDisplayState to FALSE. (This value is 
reset to TRUE in DoRead.) Also, you may need to initialize fDisplayState to the default 
arrangement. (That is not done in the template, because the items stored in the display state 
already have default values.) 


4. In DoWrite, load the display state into a display state record, and then write the record to 
the document file. 


5. In TYourDocument.DoRead, read the display state (if there is one) into a display state 
record, transfer the data to fDisplayState, and set fUseDisplayState to TRUE if there was a 
display state. 


6. In TYourDocument.DoMakeWindows, if fUseDisplayState is set, use fDisplayState to 
position the scroll bars and size and position the window. 


7. In TYourDocument.DoNeedDiskSpace, add in the amount of space needed to save the 
display state. ` 
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Templates 


{Add as a global type definition: } 
DisplayState = RECORD 
theWindowRect: Rect; 
theScrollPosition: Point; 
{If you want to save the print record for each view (normally, 
you save one for the entire document) add a field here.} 
END; 


{Add as fields of your document:} 
fDisplayState: DisplayState; 
fUseDisplayState: BOOLEAN; 


{Add to TYourDocument.IYourDocument: } 
fUseDisplayState := FALSE; {Always set to FALSE here. If you are 
how restoring a saved document, set this 
to TRUE in DoMakeDocument after 
TYourDocument returns. } 


{Add to TYourDocument .DoWrite:} 
VAR vhs: VHSelect; . 
aDisplayState: DisplayState; 
theWindow: TYourWindow; 
{In the block, between saving the print state (the call to INHERITED 
DoWrite) and saving the data.} 
WITH aDisplayState DO 


BEGIN . 
theWindowRect := fHeadWindow* .portRect; 
fHeadWindow.Focus; 


LocalToGlobal (theWindowRect .topLeft) ; 

LocalToGlobal (theWindowRect .botRight) ; 

FOR vhs := v TO h DO 

theScrollPosition.vh[vhs] := 

GetCtlValue (fShapeView. Frame. fScrollBars{vhs});: 

END; 
fDisplayState := aDisplayState; 
count := SIZEOF (DisplayState); 
FailOSErr(FSWrite(aRefNum, count, @aDisplayState)); 


{Add to TYourDocument .DoRead: } 
VAR count: LONGINT; 
ADisplayState: DisplayState; 
{In the block after calling INHERITED DoRead: } 
count := SIZEOF (DisplayState) ; 
FailOSErr (FSRead(aRefNum, count, @aDisplayState)); 
fDisplayState := aDisplayState; 
fUseDisplayState := TRUE; 


{Add to TYourDocument .DoMakeWindows: } 
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VAR vhs: VHSelect; 
aDisplayState: DisplayState; 
oldSize: POINT; 
{In the block, after you've created the window} 
IF fUseDisplayState THEN 
BEGIN F 
aDisplayState := fDisplayState; 
WITH aDisplayState.theWindowRect DO 
BEGIN 
{SH=-}MoveWindow (aWindow.fWmgrWindow, top, left, FALSE); 
SetPt(oldSize, right - left, bottom - top); {SH+} 
END; ag ' 
ResizeWindow(oldSize, FALSE); 
ForceWindowOnScreen (aWindow) ; 
FOR vhs := v TO h DO 
SetCtivValue (shapeFrame.fScrollBars([vhs], 
aDisplayState.theScrollPosition.vh[vhs]); 
shapeFrame.ScrlToSBars (FALSE); {Tell frame to scroll to indicated 
` position. } 
END; 
{Add to TYourDocument .DoNeedDiskSpace: } 
dataForkBytes := dataForkBytes + SIZEOF (DisplayState) ; 
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Views 


Creating a view 


Purpose | 


Everything displayed by a document is displayed in a view. MacApp translates between 
the view and the screen or a printer. All you have to do is create the view and provide it 
with certain methods. Applications can offer one or more views of each document. 


How to do it 


1. Define a view type that is a desendant of TView. Your view type must have the 
following methods: 


PROCEDURE TYourView.Draw(area: Rect); OVERRIDE; {Called by MacApp to 
draw the view. See the “Drawing a view” recipe. } 

PROCEDURE TYourView.IYourView; (Usually called from DoMakeView or 
DoMakeWindow after creating a view. See the “Initializing a 
view” recipe. } 


If you have more than one view type, create equivalent methods for each type. 


If a mouse click, press, or drag in the view can do something, you must also implement the 
following method: 


FUNCTION TYourView.DoMouseCommand (VAR downLocalPoint: Point; VAR Info: 
Eventinfo; VAR hysteresis: Point): TCommand; OVERRIDE; {See “Handling 
mouse events” } 


If parts of the view can be selected by the user, you usually also override 
TView.DoHighlightSelection. See the “Selecting” recipe. 


If there are menu commands that apply to the view (such as the Reduce to Fit command in 
MacDraw), override TView.DoMenuCommand. See “Menus and commands” in this 
chapter. 


If the view can be a Clipboard view, you need additional methods. See the “The 
Clipboard” recipe. 


2. Declare a field for each view in your subclass of TDocument. For example: 
fYourView: TYourView; 

The fields referencing your views will be used by your methods, not by MacApp, so you 

are free to organize them as you wish. If it makes sense in your document, you may.want 

to use a list instead of individual fields. The object-type TList provides a convenient list 


type (actually, it implements a dynamic array). See “TList” in Chapter 10 for more 
information. 
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3. Override TDocument.DoMakeViews to create your views. The interface is 
PROCEDURE TYourDocument .DoMakeViews (forPrinting: BOOLEAN); OVERRIDE; 


The parameter forPrinting is TRUE when the user is printing the document from the 
Finder. In that case, you may not need to create all your document’s views. 


` The template in this recipe shows a sample implementation of DoMake Views. 


Template z 


FUNCTION TYourDocument .DoMakeViews (forPrinting: BOOLEAN); 
VAR yourView: TYourView; 
BEGIN 
{The forPrinting parameter is TRUE only when printing from the Finder. 
You can use that value to optimize performance by creating only views 
that need to be printed.} f . 
New (yourView) ; - 
FailNIL(yourView); (See the “Failure handling” recipe.} 
yourView.TYourView (FALSE {means not for Clipboard}, SELF); 
fYourView := yourView; 
{If you have more views, create, initialize, and install them into 
fields of your document here.} 
END; 
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Initializing a view 


Purpose 


After you create a view, you call [YourView to initialize it. The initialization routine sets 
the initial size for the view and, if the view is printable, creates a print handler for the view. 


How To Do It 

_ Implement TYourView.IYourView, as shown in the template for this section. Call 
TYourView after you create your view. (Call TYourView from 
TYourDocument.DoMakeViews.) 


Template 


PROCEDURE TYourView.lYourView(forClipbodrd: BOOLEAN; itsYourDocument: 
TYourDocument) ; 
{In this case, you don’t need the forClipboard parameter. It is used so 
that a print handler object is not created for a Clipboard view. } 
VAR viewRect: Rect; 
BEGIN 
SetRect (viewRect, 0, 0, 1000, 1000); 
{The size of the view. Set to values appropriate for your view. 
This can be changed later. } 
fYourDocument :* itsYourDocument; 
{Most views have documents, but some may not.) 
IView(NIL, itsYourDocument, viewRect, sizeFixed, sizeFixed, TRUE, 
hloff) ; 
{The enumerated constant value sizeFixed is from the predefined 
SizeDeterminer enumerated type. See "Constants" in Chapter 9, 
for the other possible values. For the significance of the 
other parameters, see the description of IView under "TView"™ in 
Chapter 10.} 
{If the view can be printed, more is included. See “Using 
UPrinting” in this chapter for more information. } 
END; 
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Drawing a view 


Purpose 


When one of your application’s windows needs to be updated, MacApp calls the Draw 
method for each view displayed in the window. (Draw is defined for TView; the default 
method, TView.Draw, does nothing.) TYourView.Draw translates between the data stored 
in the document and the screen or printed page. 


How to do it 


This recipe assumes your data is organized into a list of objects that draw themselves. In 
other words, your data consists of objects organized into a list (generally stored in an 
object of type TList), and each object type has a Tltem.Draw method. TItem.Draw actually 
draws the object. If your application cannot be organized like that, have TYourView.Draw 
do the drawing itself. Note that you never call any Draw method yourself; you call 
TView.InvalidRect to invalidate the part of your view that has changed. When there is 
nothing else for the application to do, MacApp calls the Draw methods for all views that 
have invalidated areas that are actually displayed in the window. 


See the sample programs for other examples of Draw. 

Implement TYourView.Draw. The interface of that method is 

PROCEDURE TYourView.Draw(area: Rect); 

A sample method is given in the template for this recipe. That sample assumes your objects 
draw themselves and their Draw methods take no parameters. The sample also makes no 
use of the area parameter, which is a rectangle containing all invalid areas. You can use the 
area parameter to optimize your drawing. See the “Optimizing drawing” recipe. 

If you use filtered commands, this method is often coded so that it draws items that are not 
in the document or skips some items that are in the document. See the “Creating filtered 
commands” recipe for more information. 

Template 

PROCEDURE TYourView.Draw(area: Rect); 

{See the “Optimizing drawing” recipe for a discussion of the area 


parameter. } 


PROCEDURE Drawitem(item: TItem) ; 


BEGIN 
item.Draw(area); {See the “Drawing an object in a view” 
recipe. } 
END; 
BEGIN 


fItembList.Each (DrawItem) ; 
END; 
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Drawing an object in a view 


Purpose 

MacApp calls TYourView.Draw when drawing is required. You often pass the actual 
drawing on to the objects that make up your view. You generally do that so that the view 
has no need to know the form of the objects. 

How to do it i 

1. Implement TYourView.Draw as described in the “Drawing a view” recipe. 

2. Draw the object without worrying about converting coordinates. MacApp always 
adjusts the grafPort correctly before calling TYourView.Draw. In other words, you don’t 
have to worry about where on the screen the object appears or how the grafPort is set. Use 
ordinary QuickDraw calls to do the drawing in view coordinates. MacApp clips drawing to 
the part of the view visible in the window. 


3. If you want to optimize drawing by only drawing what has changed and is visible, see 
the “Optimizing drawing” recipe. 


Because drawing is so application-specific, no template is given for this recipe. 
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Optimizing drawing 


Purpose 


When MacApp calls TYourView.Draw, it passes a rectangle (the area parameter) that gives 
the invalid area of the view, which is the only part that needs to be redrawn. Whenever 
you call one of the invalidating routines, the rectangle you give is added to the invalid area. 
In addition, whenever the user scrolls the frame, the strip that appears is added to the 
invalid area. MacApp automatically adjusts the irivalid area so that only parts actually 
displayed in the frame are included. Therefore, the maximum invalid area is the size of the 
content rectangle of the frame, even if you have invalidated other areas. 


Note that moving a window does not invalidate its contents, unless it was partly off screen, 
because the system automatically moves the window’s contents along with its borders. 
Also covering a window does not invalidate the contents of the covered window. 
Uncovering a window invalidates the newly revealed parts. Similarly, when a frame 
scrolls, only the part that newly appears in the frame is invalidated. The part that was 
already displayed in the frame but has now been moved is not invalidated. 


The area parameter is always the smallest displayed rectangle that encloses all invalidated 
areas. 


This recipe describes how to use the invalid area so that you only draw the part of the view 
that needs to be drawn. 


How to do it 


If your data set consists of separate objects that are not spatially ordered, you must check 
each object to see if it is in the invalid area. There are two places in which you can check: 
in TYourView.Draw, before calling item.Draw, or in Tltem.Draw. The templates section 
of this recipe shows examples of both. l 


You need a way of identifying the rectangle containing a particular item. In the template 
methods, there is a field of Tltem called fExtentRect that is a Rect with the bounds of the 
item. You could replace fExtentRect with a functional method that returns the same value. 


(The methods in the template call RectIs Visible. If you look at the MacApp source code, 
you'll find that RectIs Visible tests if the given Rect is in the visRgn. The Window 
Manager sets the visRgn to the intersection of the visRgn and the update region before the 
update cycle begins.) 


If your data set is organized spatially (for example, in rows and columns or in paragraphs) 
you can avoid examining parts that are definitely not in the invalid area. You can do this in 
an application displaying rows and columns, for example, by finding the first and last row 
and the first and last column that intersects the invalid area. Then, only the rows and 

columns between those limits need to be drawn. The templates contain an example of this. 
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Templates 


{The following procedure shows how you can optimize TYourView.Draw.} 
PROCEDURE TYourView.Draw(area: Rect); 
PROCEDURE DrawItem(item: TItem) ; 


BEGIN 
IF RectIsVisible (item. fExtentRect) THEN 
item.Draw; 
{See the “Drawing an object in a view” recipe. } 
END; 
BEGIN 
f£ItemList .Each (Drawitem) ; 


END; 


{The following procedure shows how you can optimize TiItem.Draw. } 
PROCEDURE Titem.Draw(area: Rect); 
BEGIN 
IF RectisVisible (fExtentRect) THEN 
{Draw the object} 
END; 


{The following procedure shows how you can optimize drawing in Spatially 
organized views. } 
PROCEDURE TYourView.Draw(area: Rect); 
VAR firstRow, firstCol, lastRow, lastCol: INTEGER; 
‘rowIndex, colIndex: INTEGER; 
BEGIN 
GetDrawLimits (area, firstRow, firstCol, lastRow, lastCol); 
FOR rowindex := firstRow TO lastRow DO 
FOR colIndex := firstCol TO lastCol DO 
DrawltemAt (rowIndex, colIndex); . 
{The method DrawItemAt is not specified here. Its 
implementation depends on how you structure your data.} 
END; 


PROCEDURE TYourView.GetDrawLimits (area: Rect;VAR firstRow, firstCol, 
lastRow, lastCol: INTEGER); 


PROCEDURE PtToRowCol(aPoint: Point; VAR row, column: INTEGER) ; 


BEGIN 
row := aPoint.v DIV cRowHeight; {You define cRowHeight. } 
column := aPoint.h DIV cColWidth; {You define cColWidth. } 
END; 
BEGIN 


PtToRowCol(area.topLeft, firstRow, firstCol); 
PtToRowCol (area.botRight, lastRow, lastCol); 
lastRow := Min(lastRow, fNumRows) ; 
lastCol := Min({lastCol, fNumCols); 
{The preceding two statements assume that you maintain the 
current number of rows and columns in fields of the view. } 
END; g 
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Windows 


Creating a window 


Purpose 


A window shows a portion of a view, or portions of several views, to the user. More 
precisely, windows contain frames, and each frame shows a view. Frames (not windows) 
may be scrollable, but windows can be resized, opened, closed, and moved around the 
screen. 


This recipe deals with creating a simple, resizable window that contains a single frame, 
which may or may not be scrollable. If you want a window with more views, read this 
recipe and then proceed to the “Creating a palette window” and “Creating a window with 
two or more views” recipes. 


See the “Creating a window” section in Chapter 7 for the sequence of events when a 
window is created. 


How to do it 


1. In your resource file, you define a resource for your window. The way you define it 
depends entirely on the resource compiler you use. Here is an example of one for the 
MPW Resource Compiler, Rez: 


resource 'WIND' (1005) { 
{50, 40, 250, 450}, 
zoom roc, 
invisible, 
goAway, 
0x0, 
"<<<Untitled>>>" 

he 


The first line has the required resource type WIND and an arbitrary resource number (1005 
in this case). 


The second line defines the default initial size of the window, in screen coordinates. (Note 
that you often modify these values before displaying the window). 


The third line indicates that this window should have a zoom icon. (If you don’t want a 
zoom icon, use documentProc here. documentProc is defined in the standard MPW Rez 
types file.) 


The fourth line tells the Window Manager that this window should be initially invisible. 
You always tell the Window Manager not to display MacApp windows, even if you want 
them to be iniitally visible, because they are displayed (if appropriate by 
TApplication.Show Windows. 
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The fifth line is the window refCon. It doesn’t matter what you put here, because MacApp 
always replaces it. 


Finally, the last line defines the inital window title. Note that the triple brackets shown here 
are not displayed. The rest of the string is displayed when a new document is opened. 
When an existing document is opened, the text enclosed in brackets is replaced by the 
document name. If you want the window to have a fixed title, don’t use the brackets. You 
can also give text outside the brackets, and that text is concatenated to the document name. 


See the sample programs’ resource files for more examples. See the Window Manager 
chapter of Inside Macintosh for complete information. 


2. In your implementation, define a constant for the resource number of your window 
resource. For example: 


kIDYourWindow = 1005; 
3. Implement DoMake Views, as described in the “Creating a view” recipe. MacApp calls 
DoMakeViews immediately before DoMakeWindows, and DoMakeWindows needs to have 


the view object available. This recipe assumes that the view is stored in 
yourDocument.fView. 


4. Override TDocument.DoMake Windows for your document type. The interface of this 
method is i 


PROCEDURE TYourDocument .DoMakeWindows; OVERRIDE; 
The implementation is discussed in the rest of this recipe. 


5. The window object, along with the required Window Manager structure, is created by 
the MacApp global function NewSimpieWindow. The interface of that method is 


FUNCTION NewSimpleWindow(itsRsrcID: INTEGER; isDialogWindow: BOOLEAN; 
wantHScrollBar, wantVScrollBar: BOOLEAN; itsView: TView): TWindow; 


The itsRsrcID parameter gives the ID of the window resource. 


The isDialogWindow parameter indicates whether or not this is a dialog window. You 
usually give NOT kDialog Window here. (kDialogWindow is a predefined constant equal 
to TRUE.) 


The next two parameters, wantHScrollBar and wantV ScrollBar indicate whether or not you 
want scroll bars for the frame in this window. Use the kWantHScroliBar and 
kWantVScrollBar predefined constants here, preceded by NOT if you don’t want the scroll 
bars. 

The its View parameter is the view shown in the window. 


The template shows NewSimple Window called with parameter values that result in a 
scrollable window. , 
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Template 


PROCEDURE TYourDocument .DoMakeWindows; OVERRIDE; 


BEGIN 


VAR aWindow: TWindow; 


aWindow := NewSimpleWindow(kIDYourWindow, NOT kDialogWindow, 
kWantHScrollBar, kWantVScroliBar, fView) ; 


{If you want a nonscrollable window, precede kWantHScrollBar and 


kWantVScrollBar with NOT. You can keep one scroll bar and not the 
other, if you want. } 


AdaptToScreen(aWindow); {This is optional. It adapts the window 


size to a different screen size if 
necessary. } 


SimpleStagger(aWindow, cHStagger, cVStagger, gStagger); 


Final 


{SimpleStagger is a MacApp global routine that staggers the 
application’s windows so they do not completely cover each other. 
If you use this, you must define constants such as cHStagger and 
evVStagger, which are the number of pixels the window should be 
staggered in the horizontal and vertical dimensions, and gStagger, 
which is an INTEGER global variable used by SimpleStagger to keep 
track of how many windows have been staggered. Initialize 
gStagger to 0 in IYourApplication. If you have multiple windows 
per document, you may want to have multiple global variables like 
gStagger so the windows can be staggered in groups.} 
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Creating a palette window 


Purpose 


Some applications require a window that contains two views. The DrawShapes sample 
program is an example of this; the palette is one view, and the drawing area is another 
view. Other applications require windows with two equal areas or with three or more 
areas. , 


The areas within windows that look on views are called frames and are objects of type 
TFrame. You can have as many frames as you wish within a window, each with its own 
view. In general, all the views in a window share the same document object. 


If you want a simple window with a palette (or any nonscrollable and nonresizable area) 
and a display area, follow the directions in this recipe. 


The characteristics of a window created using the NewPaletteWindow global function used 
in this recipe are as follows: 
¢ The window contains two frames: a main frame and a palette frame. 


e The main frame may be scrollable, depending on the values passed. (In the template 
version, the main frame is scrollable.) It is resized along with the window. 


* The palette frame is not scrollable and is of a fixed size in one direction, while it takes 
up the width of the window in the other direction. 


* The palette can be vertically or horizontally oriented, depending on the value of the 
last parameter of NewPaletteWindow. If you need to create a window of a different 
form, see the “Creating a window with two or more views” recipe. 


Note: You need to have a window resource in your resource file. See the sample 
program’s resource files for examples of window resources. 


How to do it 
1. Create a view object type for each view as described in the “Creating a view” recipe. 


2. Add two fields to your document object type to store references to the view objects for 
the document. The template for this recipe assumes the fields are fMain View and 
fPaletteView. (If you have additional views, you may want to store them in a list object 
instead of individual fields.) 


3. Define a constant for the fixed dimension of the palette. In the template, it is called 
kPalette Width. 


4. Override TYourDocument.DoMake Views to create your views. In that method, create 
and initialize the views, and then store them in the fields you've added to your document. 


(See the “Creating a view” recipe.) This method is called by MacApp just before it calls 
DoMakeWindows. 


5. Override DoMakeWindows for your document. The interface of this method is 
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TYourDocument .DoMakeWindows; OVERRIDE; 


In your implementation, you first call NewPaletteWindow, the MacApp global function that 
is the key part of this method. NewPaletteWindow creates a Window Manager window 
with the requested characteristics, creates two frames, installs your views in the frames, 
and installs the window object in the document. 


The interface of NewPalette Window is 


FUNCTION NewPaletteWindow(itsRsrcID: INTEGER; isDialogWindow: BOOLEAN; 
wantHScrollBar, wantVScrollBar: BOOLEAN; itsMainView: TView; 
itsPaletteView: TView; sizePalette: INTEGER; whichWay: VHSelect) : 
TWindow; : 


The itsRsrcID parameter gives the resource ID used to determine the window template for 
the window. (The window template defines the window’s general appearance, including 
whether or not the window has a size icon, a close box, and an expand box, and the 
appearance of the title bar.) 


The isDialogWindow parameter indicates whether or not this is a dialog window. You 
usually give NOT kDialogWindow here. (kDialogWindow is a predefined constant equal 
to TRUE.) 


The next two parameters, wantHScrollBar and wantV ScrollBar, tell whether or not you 
want scroll bars for the main part of the window. The palette portion never gets scroll 
bars. Use the kWantHScrollBar and kWantVScrollBar predefined constants here, 
preceded by NOT if you don’t want the scroll bars. 


The itsMainView and itsPaletteView parameters are self-explanatory. 


The sizePalette parameter gives the size of the palette frame (not counting borders) in the 
direction specified by the whichWay parameter (see the next paragraph). In other words, if 
the palette is on the left of the window, this is the width of the frame; if the palette is at the 
top of the window, this is the height of the frame. This size is fixed. (If the window is 
made smaller or larger in the specified direction, only the main view’s frame gets larger.) 
The size of the palette in the other direction is the full size of the window and can vary. 


The whichWay parameter tells where in the window the palette frame is located. There are 
two choices: kLeftPalette and kTopPalette. 


Template 


PROCEDURE TShapeDocument .DoMakeWindows; OVERRIDE; 
VAR aWindow: TWindow; 
BEGIN ; 
aWindow := NewPaletteWindow(kIDStdWindow, NOT kDialogWindow, 
kWantHScrollBar, kWantVScrollBar, fMainView, fPaletteView, 
kPaletteWidth, kLeftPalette) ; 
END; 
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Template 

PROCEDURE TYouxrDocument .DoMakeWindows; OVERRIDE; 
VAR windowl, window2: TWindow; 

BEGIN 


windowl := NewSimpleWindow (kWindowlKind, NOT kDialogWindow, 
kWantHScrollBar, kWantVScroliBar, fView); {See the 
“Creating a window” recipe for details on this call.} 
window2 := NewSimpleWindow(kWindow2Kind, NOT kDialogWindow, 
kWantHScrollBar, kWantVScrollBar, fView); 
{You may have additional code here to restore a saved window state. 
See the “Creating a window” recipe. } 
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Handling mouse events 


You often need to track the mouse pointer after the mouse button goes down and take some 
action while the mouse moves or when the mouse button comes up. (You also 
occasionally need to track the mouse when the button is up, and take action when the 
button goes down.) Mouse actions normally fall into four groups: 


e selecting 
* buttons and other controls 
* dragging 
e drawing 


When a mouse-down event is detected by MacApp, MacApp first checks to see the location 
of the mouse when the button was pressed. If the mouse button was pressed when the 
pointer was in any part of the window except the content area (that is, if the pointer was not 
in a view), the event is handled by MacApp until it resolves into some situation involving 
your program’s code. A menu item may have been picked, for example, which results in a 
call to view. DoMenuCommand. If the user is scrolling the window, parts of the view must 
be redrawn, which results in a call to your view.Draw. 


Notes: In MacApp, the content area of a window does not include the scroll bars or 
the resize box, which are included in the Window Manager’s content area, as 
described in the Window Manager documentation in /nside Macintosh. 


Also as described in Inside Macintosh, the frame of a window is made up of the 
title bar, the resize box, and the window outline. In-MacApp, a frame is 


generalized to include either a window or a part of a window. Views are displayed 
in frames. 


If, however, the pointer was in a view (the content area of a frame) when the mouse button 
was pressed, TYourView. DoMouseCommand is called. See the “Mouse press in a view” 
section of Chapter 7 for an illustration of the sequence of events. 


DoMouseCommand is a functional method that returns a command object. If 
TYourView.DoMouseCommand determines that your application should ignore the event, 
it should retum gNoChanges (a predefined command object). If your DoMouseCommand 
method determines that the mouse-down event was the beginning of some action, it returns 
a command object to track the mouse and, eventually, process the action. In general, you 
determine what kind of mouse event occurred with DoMouseCommand. 


This section has a recipe for handling each of the four general types of mouse actions. 
Each of those recipes assume that only that type of action can occur. Following those there 
is a recipe for tracking the mouse, which contains detailed information about the mouse 
trackers used for the preceding four recipes. Then there is a recipe that shows how to 
differentiate between several possible mouse actions. 


The last recipe in this section covers the relatively rare need to track the mouse after the 


mouse button comes up. (The most common situation in which this is necessary is when 
- drawing a polygon, as in MacDraw.) 
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Selecting 


Purpose 


The user can select all or part of an object displayed in your view, in preparation for 
performing some action. You need to detect when the user is attempting to select 
something, figure out what was selected, and mark it as selected in your data set and also in 
the view by highlighting it in some way. 


You handle text selections differently from other types of selections. See the “Using 
TEView” recipe in this chapter for information. . 


For simplicity, this recipe assumes that a mouse-down event indicates a selection or 
nothing. In general, a mouse-down event indicates the beginning of one of a number of 
possible actions, and your program uses a number of criteria to figure out which action the 
user wants. See the “Handling several types of mouse events” recipe for an example of 
integrating different types of mouse actions. 


How to do it 


1) Write TYourView.DoMouseCommand so that it detects selections. The user should be 
able to select a single item and should be able to make multiple selections. 


There are several ways to handle multiple selections, generally depending on the kind of - 
data being selected. l 


Applications generally handle selections in one of two ways: 


e If your application, like DrawShapes, has discrete, independent objects scattered 
around the view, the user should be able to select individual objects by clicking on 
them. The user should also be able to make multiple selections by drawing a selection 
rectangle around several objects and add objects to the group of selected objects by 
holding down the Shift key and clicking on a new object. (Similarly, the user should 
be able to remove selections from the group by holding the Shift key and clicking ona 
selected object.) Selections don’t have to be contiguous—selecting two objects using 
Shift-click does not automatically select everything between the two objects. 


e If your application, like text or spreadsheet applications, has data organized in a 
contiguous list, selections should be contiguous arbitrary portions of the data. If the 
application deals with text, the amount selected usually depends on the number of 
clicks (that is, a single click places an insertion point, a double click selects a word, 
and a triple click selects a paragraph). In addition, the user should be able to select 
blocks of text by holding the mouse button down and sweeping the mouse across the 
text, as well as by holding the Shift key down and clicking to extend the selection. 
Extending the selection generally selects everything up to the new selection. Cell- 
based applications, such as spreadsheet programs, are similar. 
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Some applications (such as MacDraw) fall partially into both categories, depending on the 
mode chosen by the user. 


Text selections are usually handled by UTEView (see the “Using UTEView” recipe. If you 
need to handle text selections yourself, see the UTEView source code. 


If you have discrete objects displayed in your view, DoMouseCommand can follow this 
plan: 


a. Scan through your set of objects and check each to see if the mouse pointer was 
within its area. If you find the mouse pointer was over an object, check if the Shift 
key was down. If it wasn’t, mark the identified object as selected and deselect the 
previous selection. If the Shift key was down, toggle the selection status of the 
identified object. See step 2 of this recipe for a discussion of how the selection 
status of objects may be stored. 


b. If the mouse pointer was not over any object, the user may be trying to select a 
group of objects. Create a selector object, which is a type of mouse tracker. (See 
the “Tracking the mouse” recipe for a description of mouse trackers and their 
methods.) MacApp calis command.TrackMouse, command.TrackFeedback, and 
command.TrackConstrain while the button is down. You can find all the selected 
objects and mark them in TrackMouse when the trackPhase is trackRelease. (See 
Step 2 of this recipe for a discussion of marking selections.) 


A sample of a TrackMouse method for a selector object is given in the templates for this 
recipe. 


A template for DoMouseCommand is also given in the templates for this recipe. 


2. Create a DoHighlightSelection method for your view. yourView.DoHighlightSelection 
is called by MacApp after MacApp calls yourView.Draw. The interface for 
DoHighlightSelection is: 


PROCEDURE TYourView.DoHighlightSelection(fromHL, toHL: HLState); 
OVERRIDE; 


HLState is an enumerated type with values hlOff, hlDim, and hlOn. Dim highlighting 

(which is not part of the user interface standard and is an optional enhancement) can be 

used instead of no highlighting when the window is not active. You define the inactive 
HLState by setting the view’s fHLInactive field. You normally do that in TYourView. 


DoHighlightSelection finds all selections and turns highlighting on, off, or to dim. It-is 
called by MacApp when the window showing the view is activated, deactivated, or when 
the view is updated. When the view is being updated, the fromHL state is always hlOff 
(because the update region is always erased and redrawn). When the window is activated, 
the from state is fHLInactive, a field of the view, which can be hlOff or hlDim. When the 
window is deactivated, the to state is fHLInactive. 


You call DoHighlightSelection yourself when the selection changes. A sample 
implementation is given in the templateS for this section. The template allows multiple. 
selections, with each object marked as selected or not selected. 


Unlike most methods that draw in the view, DoHighlightSelection can be called from other 


methods. When the selection is changed, you may call DoHighlightSelection(hlOn, hlOff) 
to remove highlighting from the old selection and then call DoHighlightSelecnon(hloff, 
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hlOn) to highlight the new selection. You should focus on the current view before callin g 
DoHighlightSelection. ; 


3. Record what objects (or parts of objects) are selected. There are many ways you could. 
record this information. Some common ways are listed here: 


e If there is always only one selection, the selection is somehow indicated separately 
from the list of objects (probably stored in a field of the document, or, if that is not 
meaningful, of the view), and DoHighlightSelection simply highlights the current 
selection. 


e The document (or view, if necessary) has a list of selected objects separate from the 
list of all objects. DoHighlightSelection scans through that list and highlights all of 
them. 


e Each object is marked as selected or not selected. One way to mark them is to have a 
BOOLEAN field, flsSelected, in each object. When the object is initialized, you set 
that field to FALSE. DoHighlightSelection scans through the list of objects and 
highlights any that have fIsSelected TRUE. 


° There isa BOOLEAN function that decides whether or not an object is selected. 
DoHighlightSelection can scan through the list of all objects and highlight those for 
which this function returns TRUE. 


Templates 


FUNCTION TYourView.DoMouseCommand (VAR downLocalPoint: Point; 
f VAR info: EventInfo; 
VAR hysteresis: Point): TCommand; 
VAR hitItem: TItem; 
selector: TYourSelector; 


PROCEDURE CheckHit (item: TiItem); 

BEGIN . 

IF {for example} PtInRect (downLocalPoint, item.bountRect) THEN 
hitItem := item; 

END; 


BEGIN | 
item := NIL; 
IF NOT info.theShiftKey THEN 
DeSelect; {This is a method you must design and add to your view 
to remove marking from the current selection or 
selections. } 
fitemList .Each(CheckHit); (This TList-type field of the view holds 
all the application’s items. The code 
here assumes that the list is ordered 
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back~to-front and the frontmost object is 
the one the user selects.} 
‘IF item = NIL THEN 
BEGIN {begin a selection rectangle} 
New (selector); 
FailNIL (selector); 
selector.ISelector (SELF, info.theShiftKey) ; 
DoMouseCommand := selector; 
END 
ELSE 
BEGIN {one object selected or toggled} 
DoMouseCommand := gNoChanges; 
hitItem.fIsSelected :* NOT hitItem.fIsSelected; 
END; i 
END; 


FUNCTION TYourSelector.TrackMouse (aTrackPhase: TrackPhase; VAR 
anchorPoint, previousPoint, nextPoint: Point; mouseDidMove: BOOLEAN): 
TCommand; 

VAR yourDocument: TYourDocument; 


PROCEDURE CheckHit (item: TItem); 

BEGIN 
{Here check if the item is in the rectangle marked by the mouse 
between anchorPoint and nextPoint. If it- is, mark it selected 
or deselected or add it to the list or remove it from the list 
of selected items, depending on the state of the Shift key 
stored in the selector object.} 

END; 


BEGIN 
TrackMouse := SELF; 
IF aTrackPhase := trackRelease THEN 
BEGIN . 
yourDocument := TYourDocument (fView.fDocument) ; 
yourDocument .Each(CheckHit); {Assumes items are in a TList 
list.} 
£View .DoHighlightSelection(hloff, hlon); 
TrackMouse := gNoChanges; 
END; 
END; 


PROCEDURE TYourView.DoHighlightSelection(fromHL, toHL: HLState) ; 


PROCEDURE HighlightItem(item:TItem) ; 
BEGIN 
IF item. fIsSelected THEN 
item.Highlight (fromHL, toHL); 
END; 


BEGIN 


fItemList .Each (HighlightItem) ; 
END; 
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Dra gging 


Purpose 


Many applications have discrete objects that can be moved around the view. They are often 
moved by the user dragging the object with the mouse. 


For simplicity, this recipe assumes that a mouse press indicates that the user wants to drag 
an object or has no meaning. In general, a mouse press may indicate a number of possible 
actions, and your program uses a number of criteria to figure out which action the user 
wants. See the “Handling several types of mouse events” recipe for an example of 
integrating different types of mouse actions. l ; 


How to do it 


1. Implement DoMouseCommand so that it creates a dragger object if the mouse has been 
clicked on an object. (If the mouse has not been clicked on an object, nothing should be 
done and DoMouseCommand should return gNoChanges to indicate that no valid action 
has occurred.) The next step discusses dragger objects. 


The DoMouseCommand in the templates assumes that the object located under the mouse 
pointer should be marked as selected and any previous selection should not be deselected, a 
choice of action that is rarely appropriate but is used here because this recipe ignores all 
selection issues. See the “Selecting” recipe for a full discussion of selections. 


2. Implement a dragger object. Here is a sample interface of a dragger type: 


TYourDragger = OBJECT (TCommand) ; 
fYourDocument: TYourDocument; 
fYourView: TYourView; 
fDeltaH: INTEGER; 
fDeltaV: INTEGER; 


PROCEDURE TYourDragger.IDragger(view: TYourView) ; 

FUNCTION TYourDragger.TrackMouse (aTrackPhase: TrackPhase; 
VAR anchorPoint, previousPoint, 
nextPoint: Point; mouseDidMove: 
BOOLEAN): TCommand; OVERRIDE; 

PROCEDURE TYourDragger.DoIt; OVERRIDE; 

PROCEDURE TYourDragger.UndoIt; OVERRIDE; 

PROCEDURE TYourDragger.Redolft; OVERRIDE; 

PROCEDURE TYourDragger.TrackFeedback; OVERRIDE; 

PROCEDURE TYourDragger.FixSelection; 

PROCEDURE TYourDragger.MoveBy (movelIt: BOOLEAN) ; 

END; 


You need to override TrackFeedback because you generally need to give feedback other 
than the standard flickering rectangle, which is only appropriate for selecting areas. If you 
‘want to constrain the mouse (for example, to conform to a grid), also override 
TrackConstrain. TrackFeedback and TrackMouse are discussed later in this recipe. 
TrackConstrain is discussed in the “Tracking the mouse” recipe. 
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A dragger object is a type of mouse tracker. See the “Tracking the mouse” recipe for 
details on mouse trackers. 


3. Add the following field to your view: 
fDragging: BOOLEAN; 


This field is used to determine if the mouse is actually moving. It is used for a number of 
optimizations, but is primarily necessary so that TrackMouse can determine when the 
mouse has first moved. See the discussion of TrackMouse later in this recipe for an 
explanation. 


In your IYourView method, initialize (Dragging to FALSE. 


4. Define a command constant for the dragging command. Although dragging is not a 
menu command, it must have its own unique constant, such as 


cDragCommand = {Use numbers above 1000 for your application’s commands. 
Building blocks can use numbers above 500.}; 


5. In your TYourView.Draw method, before drawing each item, you may want to test if 
fDragging is TRUE and the item is currently selected. If both conditions are TRUE, you 
might not draw the item in Draw. Instead, you may draw it in its current position in 
TrackFeedback. (Whether or not you do this depends on what you want the user to see 
during a dragging operation.) Similarly, you may want to prevent highlighting in your 
DoHighlightSelection method if the item is being dragged. 


6. Implement [Dragger. Note that fView.fDragging should be set to FALSE here because 
at the time the dragger object is created, you cannot assume that dragging will actually 
occur, only that it is possible. Also, you ordinarily call ICommand to initialize the 
command. (In some cases, you may call another method which itself calls ICommand.) 
No template is given for this method; see the sample program DrawShapes for an example. 


7. Implement TrackFeedback so it shows the dragged item or items as they move. The 
feedback should, of course, be chosen as appropriate for your application, but, to prevent 
unnecessary drawing, you should gate your feedback by checking if fView.fDragging is 
TRUE and if mouseDidMove is TRUE. (The parameter mouseDidMove is passed to your 
TrackFeedback method by MacApp. It indicates whether or not the mouse moved since 
the last time TrackFeedback was called.) ` 


8. Add the following method to the interface of your view type: 

PROCEDURE TYourView.PrepareToTrack; 

This method prepares the view for dragging. To do so, it should erase any selected items 
(unless you don’t want your application to do that) and set fView.fDragging to TRUE. If 
your view contains items that might overlap—in which case, when you erase the selected 
items, you might also erase unselected items that overlap the selected items, call 
UpdateEvent for the view’s frame so that the frame is redrawn, A sample of this is shown 
in the tempates for this recipe. 


9. Implement TrackMouse. 
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When aTrackPhase is trackMove, check the value of view.fDragging. If view.fDragging is 
FALSE, this is the first time that TrackMouse has been called in the trackMove phase, and 
it is time to prepare for tracking. First, call the view’s DoHighlightSelection(hlOn, hlOff) 
to remove highlighting from the selection. Then, call the view’s PrepareToTrack method. 
(See the previous step of this recipe.) Finally, focus on the view’s frame, because 
PrepareToTrack may have changed the focus. If view.fDragging is TRUE, you don’t 
have to do anything, unless your application has actions that should be done at this time. 


When aTrackPhase is trackRelease, if view.fDragging is still FALSE, you should return 
gNoChanges, because the user has done nothing. If view.fDragging is TRUE, it is time to 
set up for moving the items that were dragged. (If this drag doesn’t change the document, 
you can carry out the action of the command here, and then return gNoChanges. This 
recipe assumes that a dragging action changes the document.) To set up for moving, 
calculate the change in position, and store those values in fDeltaH and fDeltaV. Finally, 
reset view.fDragging to FALSE. 


A sample TrackMouse method is shown in the template. 


10. If a dragger changes the document, the action of the dragger is not performed in 
TrackMouse (although TrackFeedback may make it appear to the user that the action of the 
dragger has been carried out); instead, the action is performed by the Dolt method. Dolt is 
. called by MacApp after the mouse button comes up. A sample Dolt method is given in the 
templates. The sample assumes that you have a MoveBy method, which actually moves 
the object. A sample MoveBy method is shown in the templates. 


You should also implement Undolt and Redolt for your dragger type. Using MoveBy, 
rather than actually moving the object in Dolt, makes implementing Undolt and Redolt 
easier. Samples of Undolt and Redolt are given in the templates. The next step of this 
recipe has more discussion of what is necessary to properly undo and redo this command. 


Notice that MoveBy checks all objects and moves any that are selected. The sample 
assumes that the objects are marked as selected or not selected. Your application may 
maintain its selections differently or may allow only a single selection. See the “Selecting” 
recipe for details on marking selections. 


MoveBy as shown in the templates invalidates the original position of the object. The 
DrawShapes program handles that invalidation differently, and also generally handles 
dragging items differently. You may want to examine DrawShapes to get a different 
perspective on this operation. . 


11) When you undo and redo this command, you must be sure that the selections are set 
correctly. Because selections do not change the document, the dragger command is not 
committed just because the user changes the selection. Therefore, the user might change 
the selection before choosing Undo. You must therefore have a record of what was 
selected when the dragger command was executed, and you must restore the selection 
when Undo and Redo are chosen. 


Implement TYourDragger.FixSelection so that it restores the selections in effect when the 
command was first done. You can record the old selections in any of the ways that you can 
record currect selections. The sample in the templates gives a field fWasSelected to every 
object, as well as a field fIsSelected. The currect selection is indicated in fIsSelected; the 
selection at the time of the command is in fWasSelected. When the command is undone or 
redone, fIsSelected has its value replaced by fWasSelected. 
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Have Undo and Redo call FixSelection before calling MoveBy. 


Templates 


FUNCTION TYourView.DoMouseCommand (VAR downLocalPoint: Point; 
VAR info: EventiInfo; 
VAR hysteresis: Point): TCommand; 
VAR 
hitItem: TItem; 
dragger: TYourDragger; 


FUNCTION CheckHit (item: TItem): BOOLEAN; 
BEGIN 
IF (test location for hit} THEN 
CheckHit := TRUE; 
ELSE 
CheckHit := FALSE; 
END; 


BEGIN 
hitItem := NIL; 
hititem := £YourDocument.fItemList.FirstThat (CheckHit) ; 
IF hitItem<> NIL THEN 
BEGIN 
iMark item as selected} 
New (dragger) ; 
FailNIL(dragger) ; 
dragger.IDragger (SELF); 
DoMouseCommand := dragger; 
END 
ELSE 
DoMouseCommand := gNoChanges; 
END; 


PROCEDURE TYourView.PrepareToTrack; 


PROCEDURE EraseItem(item: TItem); 
VAR r: Rect; 
BEGIN 
IF item.fIsSelected THEN 
BEGIN 
r := item.fExtentRect; 
InsetRect(r, -2, -2); 
fPrame.InvalidRect (r); 
END; 
END; 


BEGIN 
fYourDocument.fItemList .Each (EraselItem) ; 
fDragging := TRUE; 
fF rame .UpdateEvent; 

END; 


FUNCTION TYourDragger.TrackMouse (aTrackPhase: TrackPhase; 
. VAR anchorPoint, previousPoint, 
nextPoint: Point: 
mouseDidMove: BOOLEAN): TCommand; 
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BEGIN > 
TrackMouse := SELF; 
IF aTrackPhase = trackMove THEN 
IF NOT fYourView.fDragging THEN {This is the first move} 
BEGIN : 
fYourView.DoHighlightSelection(hlon, hloff); 
fYourView.PrepareToTrack; 
fYourView.fFrame.Focus; {PrepareToTrack changes the Focus} 
END; 
ELSE IF aTrackPhase = trackRelease THEN {Set up for moving the 
items(s) } 
BEGIN - 
IF fYourView.fDragging THEN {Actually did move} 
BEGIN 
fDeltaH := previousPoint.h - anchorPoint.h; 
fDeltaV := previousPoint.v -~ anchorPoint.v; 
fYourView.fDragging := FALSE; 
END 
ELSE 
TrackMouse := gNoChanges,; 
END 
END; 


PROCEDURE TYourDragger.Dofit; 
BEGIN 

MoveBy (TRUE) ; 
END; 


PROCEDURE TYourDragger.UndolIt; 
BEGIN 

FixSelection; 

MoveBy (FALSE) ; 
END; 


PROCEDURE TYourDragger.RedoIt; 
BEGIN 

FixSelection; 

MoveBy (TRUE) ; 
END; 


PROCEDURE TYourDragger.MoveBy(movelIt: BOOLEAN) ; 


PROCEDURE Moveltem(item:TItem) ; 


BEGIN . 
If {the item is selected} THEN 

BEGIN : 
{invalidate the item’s old image. } 
{Move the item’s definition. } 
{Invalidate the item’s new position.} 
END; 

END; 

BEGIN 


fYourView.fFrame.Focus; 


TYourDocument (fItemView.fItemDocument) .fItemList.Each (Moveltem) ; 
END; 


PROCEDURE TYourDragger.FixSelection; 
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PROCEDURE FixItem(item:TItem) ; 
BEGIN 
item.fIsSelected := item. fWasSelected; 
IF item.fIsSelected THEN 
{Invalidate the item in the view.} 
END; 


BEGIN 
f£YourDocument .Deselect; {You should implement this method so it 
l deselects all selections and invalidates 
g all of the former selection’s images so 
the highlighting is removed by the next 
À : update. } 
£YourDocument .fItemList .Each (FixItem) ; 
END; 
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Drawing with the mouse 


Purpose 


Many applications allow the user to draw using the mouse. This recipe shows how to 
implement that operation. 


For simplicity, this recipe assumes that a mouse press indicates that the user wants to draw 
or the mouse press has no meaning. In general, a mouse press may indicate a number of 

- possible actions, arid your program uses a number of criteria to figure out which action the 
user wants. See the “Handling several types of mouse events” recipe for an example of 
integrating different types of mouse actions. 


How to do it 


1. When DoMouseCommand detects that a drawing operation has started, it should create a 


sketcher object, because drawing changes the document. The templates give the structure 
of DoMouseCommand. - 


2. Use a sketcher command object to track the mouse, to provide appropriate feedback as 
the mouse moves, and, when the mouse button comes up and a valid item has been drawn, 
to add the new item to the document. Here is a sample interface for a sketcher type: 


TYourSketcher = OBJECT (TCommand) ; 
fYourView: TYourView; 
fItem: TItem; {The new item. } 
PROCEDURE TYourSketcher.ISketcher(view: TYourView); 
FUNCTION TYourSketcher.TrackMouse(aTrackPhase: TrackPhase; VAR 
anchorPoint, previousPoint, nextPoint: Point; 
mouseDidMove: BOOLEAN): TCommand; OVERRIDE; 
PROCEDURE TYourSketcher.DoIt; OVERRIDE; 
PROCEDURE TYourSketcher.UndoIt; OVERRIDE; 
PROCEDURE TYourSketcher.RedoIt; OVERRIDE; 
END; 


If you want to give feedback other than the standard flickering rectangle (which you will 


usually want to do), also override TrackFeedback. If you want to constrain the mouse, to 
stay in the bounds of the view, to draw a circle or a square, or to conform to a grid, for 
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example, also override TrackConstrain. TrackFeedback and TrackConstrain are discussed 
in the “Tracking the mouse” recipe. 


The templates give the structure of TrackMouse, Dolt, Undolt, and Redolt. 


3. If you want, you can continue drawing when the mouse button comes up. This is done, 
for example, when a polygon is drawn in MacDraw or MacPaint. That is discussed in a 
separate recipe, “Tracking the mouse when the mouse button is up”. 


Template - 


FUNCTION TYourView.DoMouseCommand (VAR downLocalPoint: Point; VAR info: 
EventInfo; VAR hysteresis: Point): TCommand; 
VAR sketcher: TYourSketcher; 
BEGIN 
New (sketcher); 
Sketcher.ISketcher (SELF); 
DoMouseCommand := sketcher; 
END; 


FUNCTION .TYourSketcher.TrackMouse (aTrackPhase: TrackPhase; VAR 
anchorPoint, previousPoint, nextPoint: Point; mouseDidMove: 
BOOLEAN) : TCommand; 

VAR aniItem: Titem; 
BEGIN 
TrackMouse := SELF; 
IF aTrackPhase = trackRelease THEN 
IF {not a legal item} THEN 
TrackMouse := gNoChanges 
ELSE 
BEGIN 

New (anItem) ; 

fitem := anItem; {You can’t use fItem in New because the 

heap might compact. } 

{Extract the information you need from the mouse down 

and up points and initialize the new item.} 

END; 

END; 


PROCEDURE TYourSketcher.DoIt 
BEGIN 


TYourDocument (gDocument) .fItemList.InsertFirst (fItem) ; 
END; ` 


PROCEDURE TYourSketcher.UndoIt; 
BEGIN l 

TYourDocument (gDocument) .fItemList.Delete(fItemList.First); 
END; 


PROCEDURE TYourSketcher.RedolIt,; 
BEGIN 

TYourDocument (gDocument) .fItemList.InsertFirst (fItem) ; 
END; i 
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Tracking the mouse 
Purpose 


After you've created a command object, yourMouseCommand, and retumed it through 
DoMouseCommand (see the discussion at the beginning of this section), MacApp tracks 
the mouse, calling yourMouseCommand.TrackMouse repeatedly. 


TrackMouse has a parameter aTrackPhase. MacApp calls TrackMouse once with a track 
phase of trackPress, then calls repeatedly with a track phase of trackMove, and then calls 
once with a track phase of trackRelease. 


If you do not want to take any action depending on the track phase and the action of the 
mouse command changes the document, you do not have to override TrackMouse. 


You generally have to override TrackMouse. If you want to take some other action 
depending on the trackPhase or the mouse location, override TrackMouse. In addition, if 

_ the command may not change the document, override TrackMouse. The default version of 
_ TrackMouse returns the command object itself as the function return value, which results in 
always marking the document as changed after the mouse button is released. 


If you want to give nonstandard feedback as the mouse moves, override TrackFeedback, as 
described below. If you want to constrain mouse movement in some way, override 
TrackConstrain, also described below. 


How to do it 
1. Add the following to your mouse command object type definition: 


FUNCTION TYourMouseCommand.TrackMouse(aTrackPhasé: TrackPhase; VAR 
anchorPoint, previousPoint, nextPoint: Point; mouseDidMove: BOOLEAN): 
TCommand; OVERRIDE; 


In your implementation of TrackMouse, you should return SELF, so that MacApp 
continues to call yourMouseCommand.TrackMouse. You can also return another 
command object, in which case that command object takes over tracking the object. 
(MacApp frees the old command object for you.) On trackRelease, if no changes have 
been made to the document, you can return gNoChanges, which tells MacApp to free the 
command object. It also tells MacApp to not commit and free the last command object. (If 
gNoChanges is not returned, MacApp automatically calls Commit for the last command and 
frees that command. The result is that the last command can no longer be undone, which 
may not be appropriate.) 


No template is given for TrackMouse because its form varies greatly. See the other recipes 
of this section for samples. : 


2. If you retum a command object, MacApp calls yourMouseCommand.Dolt when the 
mouse is released. If the command can be undone, you normally perform the action of the 
mouse command in Dolt. If the command cannot be undone, you can perform the action 
in TrackMouse when the track phase is trackRelease. In that case, retum gNoChanges 
instead of your own command object. No template is given for 
TYourMouseCommand.Dolt. 
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3. The method yourMouseCommand.TrackFeedback is called by MacApp as the mouse 
moves. TCommand.TrackFeedback produces a shadowy (black pen, XOR mode) box 
between the point where the mouse button was pressed and the current mouse position. If 
you want different feedback, add the following to your definition of 
TYourMouseCommand: 


PROCEDURE TYourMouseCommand.TrackFeedback (anchorPoint, nextPoint: Point; 
turnitOn, mouseDidMove: BOOLEAN); OVERRIDE; ' 


You can, for example, change the pen state or mode and then call INHERITED 
TrackFeedback, or you can provide completely different feedback. 


No template is given for this method. 
4. If you want to constrain mouse movement in some way, such as is done when the grid 
is on in MacPaint: 


a. Set yourMouseCommand.fConstrainsMouse to TRUE. (You can do that in 
TYourMouseCommand.) fConstrainsMouse is a field of TCommand. 
fConstrainsMouse defaults to FALSE. When that field is TRUE, MacApp calls 
yourMouseCommand. TrackConsrrain. 


b. Override TCommand.TrackConstrain. Here is the interface for that method: 


PROCEDURE TYourMouseCommand.TrackConstrain(anchorPoint, 
previousPoint: Point; VAR nextPoint: Point); OVERRIDE; 


This is called only if fConstrainsMouse is TRUE. In your implementation, change 
the value of nextPoint according to your program’s requirements. No template is 
given for this method. 
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Handling several types of mouse events 


Purpose 


The preceding recipes in this section assume that only one type of mouse event is possible. 
Few applications are so limited. In general, your view. DoMouseCommand method must 
differentiate between possible types of events and take appropriate action. 


There are two basic ways to differentiate between possible mouse events: based on mode 
and based on location. Programs generally use a combination of these methods. For 
example, the DrawShapes sample program has two modes: when the arrow cursor is 
displayed and when a drawing pointer is displayed. In the arrow pointer mode, you can 
select individual shapes, select an area, and drag shapes, and the program tells which one 
you want to do basically by where the mouse button went down. 


When one of your application’s view. DoMouseCommand methods is called, indicating a 
mouse down event in one of your application’s views, the application must determine what 
kind of action is beginning and (generally) create an appropriate type of command object, 
which then tracks the mouse and carries out the action of the command. This recipe 
generally covers the needed steps up to-the point of creating a command object for the 
mouse command. See the individual recipes in this section for details on implementing 
those command objects. 


How to do it 


1. Implement DoMouseCommand for each view type that needs to respond to a mouse 
down event. DoMouseCommand is a function that retums a TCommand-type object. The 
interface for DoMouseCommand is 


FUNCTION TYourView.DoMouseCommand (VAR downLocalPoint: Point; VAR info: 
EventiInfo; VAR hysteresis: Point): TCommand; OVERRIDE; 


A sample skeleton for DoMouseCommand is given in the template for this recipe. That 
sample is very sketchy because the form of DoMouseCommand depends on what your 
particular application does. 


Your DoMouseCommand method must first determine if the user made a selection or is 
indicating some other action. 


The sample in the template then checks for certain conditions and creates an appropriate 
command object depending on the conditions. 


The details of what happens once you have determined the type of action needed are not 
given in this recipe. See the first five recipes of this section for details. 


YourView.DoMouseCommand often creates a mouse command object. There may be 
several types of mouse command objects. If the event is handled entirely by 
DoMouseCommand (which should be done only for mouse events that do not change the 
document), or if the event does not produce an action, TYourView. DoMouseCommand 
should return gNoChanges, a global variable of type TCommand that indicates no changes 
to the document have occurred. (You can also return gNoChanges later, if it turns out that 
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no changes have been made. See the discussion of TrackMouse in the “Tracking the 
mouse” recipe.) 


Command objects retumed through DoMouseCommand are expected to have different 
methods than other command objects. The “Tracking the mouse” recipe explains what is 
required of those methods. 


Template 


FUNCTION TYourView.DoMouseCommand (VAR downLocalPoint: Point; VAR info: 
EventInfo; VAR hysteresis: Point): TCommand; 
VAR 
firstMouseCommand: TFirstMouseCommand; 
secondMouseCommand: TSecondMouseCommand; 
BEGIN 


DoMouseCommand := gNoChanges; {n case no action found that changes 


the document. } : 
{Check for selections here. See “Selections” in the Cookbook. } 
IF {the action indicates a firstMouseCommand} THEN 
BEGIN 
New (firstMouseCommand) ; 
firstMouseCommand.IFirstMouseCommand (SELF, downLocalPoint); 
{Those parameters are only an example.} 
DoMouseCommand := firstMouseCommand; 
END 
ELSE IF {the action indicates a secondMouseCommand} THEN 
BEGIN 
New (secondMouseCommand) ; 
secondMouseCommand. ISecondMouseCommand (SELF, downLocalPoint); 
{parameters only examples} 
DoMouseCommand := secondMouseCommand; 
END; 
END; 
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Tracking the mouse when the mouse button is up 


Purpose 


Some applications must occasionally track the mouse and possibly provide feedback when 
the mouse button is up. An example of this is in MacDraw, when you draw a polygon. In 
that case, you mark the end of the first side of the polygon by letting the mouse button up 
and draw the second side with the button up. The second side is marked when the mouse 
button goes down again. 


You track the mouse when the mouse button is down with DoMouseCommand and : 
TrackMouse, as described in the “Tracking the mouse” recipe. MacApp does not call either 
of those methods when the mouse button is up. This recipe describes what you have to do 
to track the mouse with the button up. 

How to do it 

1. Override DoSetCursor. The interface to DoSetCursor is 

FUNCTION TYourView.DoSetCursor(localPoint: Point): BOOLEAN; OVERRIDE: 
DoSetCursor for the view whose frame contains the mouse is called repeatedly during idle 
time, that is, when the user is doing nothing but moving the mouse. The default version of 
DoSetCursor, contains only one line of code: 

DoSetCursor := FALSE; 


This line simply informs MacApp that the pointer should be the arrow pointer. To track the 
mouse, you need to add your tracking and feedback functions to this method. 


2. Implement DoMouseCommand so that it recognizes that you were tracking the mouse 
while the mouse button was up and takes appropriate action. The interface of 
DoMouseCommand is 


FUNCTION TYourView.DoMouseCommand (VAR downLocalPoint: Point; VAR info: 
EventiInfo; VAR hysteresis: Point): TCommand; OVERRIDE; 
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Standard editing commands 


Undo 


Purpose 


The Undo menu command should be implemented for any user action that changes the 
document. In other words, itis not usually desirable to implement Undo for actions like 
scrolling or selections that do not actually change the data, but you should implement Undo 
for actions like adding or deleting objects from the document’s data set. 


The Undo menu command is automatically enabled by MacApp when there is a command 
object that has been done and that has its fCanUndo field set to TRUE and that has not been 
superseded by another command object. (Note that MacApp cannot tell if the command 
object actually has an implemented Undolt or Redolt method.) As long as you return 
gNoChanges from DoMenuCommand and from TrackMouse when the track phase is 
trackRelease, the Undo command remains enabled for the last undoable command. When a 
different type of command object is returned, MacApp calls command.Commit for the 

` previous command object (unless that command was undone and not redone) and enables 
or disables Undo depending on whether the new command object can be undone. 


How to do it 


The Undo command is handled by the current command object. Whenever a user action (a 
mouse action, a menu choice, or typing) will change the document, a command object 
should be created. (See “Handling Mouse Events” and “Menus and Commands” in this 
chapter.) When the command is initially done, MacApp calls the command object’s Dolt 
method. When the user chooses Undo the first time (or any odd number of times), 
MacApp calls the command object’s Undolt method. When Undo is chosen a second time 
(or any even number of times), MacApp calls the command object’s Redolt method. 


If the command is simple, you normally change the document’s data with Dolt, Undolt, 
and Redolt, and those methods invalidate any affected portions of the view or views. 


If the command has results that are too complicated to undo directly, Dolt and Redolt apply 
a filter that makes the view appear as if the data had actually been changed, but do not 
actually change the data. Undolt simply removes the filter.. (All three methods must still 

- invalidate the changed parts of the view. When a filter is applied, it is usually implemented 
with a flag that indicates a filtering method should be called from the drawing methods, 
which are themselves called during the update cycle.) To change the document’s data, 
override TCommand.Commit so that Commit changes the data. Commit is called before 
the command is freed, usually just before another command object is created or when the 
document is saved. (Note that Commit is not called if the command was in undo phase.) 


The default TCommand methods Commit, Dolt, and Undolt do nothing. 


See the “Creating filtered commands” recipe for more information about filtering. 
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Cut and Copy 


Purpose 


The Cut, Copy, and Paste commands should be implemented in all Macintosh applications 
to allow transfer of data among and within applications and desk accessories. In order for 
this recipe to work, you must also implement the “Supporting the Clipboard” recipe. 


This recipe deals with the Cut and Copy commands, which are generally handled by a 
single type of object. The next recipe deals with the Paste command. 


The Cut command removes the selected information from the view (and generally also from 
the document) and places the information in the Clipboard. The Copy command copies the 
selected information to the Clipboard but does not remove the original. 


How to do it 


1. In the appropriate DoMenuCommand method (usually belonging to the view but 
possibly to the document) create a cut/copy command object of a type that is a descendant 
of TCommand. (Some programs may need separate command objects for cut and copy, 
although generally a copy is identical to a cut except that the information is not removed 
from the document.) 


2. In the [YourCommand method of your cut/copy command object, set 
fChangesClipboard to TRUE after calling ICommand. 


3. In the Dolt method of your Cut/Copy command object, create a view for the cut or 
copied data. The view is typically of the same type as the one holding the selection and, 


again typically (but not universally), you must create a document object to go with the view 
object. 


4.After you initialize this view, call TApplication.ClaimClipboard to install the view in the 
Clipboard. The interface for that method is 


PROCEDURE TApplication.ClaimClipboard(clipView: TView) ; 


ClaimClipboard automatically preserves a reference to the old Clipboard view, in case this 
command is undone. 


If this is a cut command, cut the data from your document, and invalidate the representation 
of the data in the. view. 


You must not call ClaimClipboard in your Undolt or Redolt methods. MacApp 
automatically replaces the old Clipboard contents when Undo is picked and automatically 
replaces the new Clipboard when Redo is picked. 


In the case of a copy command, Undolt need do nothing except, if you wish, restore the 
selection state at the time the command was originally done (although MacApp restores the 
old Clipboard view for you). Redolt needs to take exactly the same action as Dolt, 
possibly acting to restore the last selection. 
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No template is given for this recipe and the next, because the methods depend too much on 
application-specific conditions. 
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Paste 


Purpose 


The Cut, Copy, and Paste commands should be implemented in all Macintosh applications 
to allow transfer of data between and within applications and desk accessories. 


The Paste command pastes data from the Clipboard into the application’s document. The 
Clipboard may contain data cut or copied from your application or from another 
application. In the second case, the data is usually available as TEXT data (a string of 
ASCII characters) and/or PICT data (PICT is a QuickDraw picture). 


In order for this recipe to work, you must also implement the “Supporting the Clipboard” 
recipe. That recipe deals with the tasks required of a Clipboard view, and the methods 
needed to support a Clipboard view. This recipe deals with the Paste command object 
itself. 


How to do it 


1. In the DoSetUpMenus method for the object whose DoMenuCommand method handles 
Paste (usually the view but possibly the document), tell MacApp what kind of data you can 


paste. You do this by calling the global procedure CanPaste. The interface of that routine 
is . 


PROCEDURE CanPaste(aDataType: ResType) ; 


Call this procedure once for each Clipboard data type you can handle. (See the 
“Supporting the Clipboard” recipe for a more about Clipboard data types.) If you can paste 
. More than one kind of data (you should, ideally, be able to handle PICT and TEXT data as 
well as your own types), make the calls in inverse order of preference: from the least 
preferred to the most preferred. 


Note that you never call Enable or EnableCheck for the Paste command. MacApp tests the 
contents of the Clipboard for the Clipboard data types you specify in your CanPaste calls 
(by calling Clipboard View.ContainsClipType) and enables or disables the command 
accordingly. 


2. Create a paste command object (discussed in the next step) when your 
DoMenuCommand method finds the command number cPaste. Given the CanPaste calls 
made in DoSetupMenus, you can be certain that information of some type you can handle is 
present in the Clipboard any time you get a cPaste command number. 


3. Define a paste command object type that is a descendant of TCommand. The object 
should be created and initialized in DoMenuCommand when a cPaste command number is 
received. The action of the command is carried out in the pasteCommand.Dolt and Redolt 
methods. 


To get the data that is to be pasted, allocate an empty handle and pass the handle to the 
application’s GetDataToPaste method. The interface of this method is 


FUNCTION TApplication.GetDataToPaste(aDataHandle: Handle; VAR dataType: 
ResType) : LONGINT; : 
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If you only want to find out the size of the data (probably to determine whether or not there 
is enough memory to carry out the requested paste operation), pass NIL as aDataHandle. 
When the data is in the public scrap (also called the desk scrap), this call is equivalent to the 
Scrap Manager routine GetScrap. Do not call GetScrap directly, because the data may be in 
the private (application) scrap. 


You do not choose the data type here; that is determined by your CanPaste calls in 
DoSetUpMenus. The data type passed to you is the most preferred type available. If you 
can paste more than one type, you probably need to use IF statements to branch according 
to the type; note MPW Pascal does not allow CASE statement branches on four-byte 
quantities. : l 
The data referred to by the handle is a copy of the data in the Clipboard. You can do 
anything you want with that data or the handle. 


GetDataToPaste (which you rarely need to override) calls gClipView.GivePasteData. See 
the “The Clipboard” recipe for details on implementing that method. 


Paste operations should almost always be undoable (see the “Undo” recipe earlier). See 
Menus and Commands for more information on commands, 
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Menus and commands 


Creating menu commands 


Purpose 
In general, all commands that are not mouse actions or typing are menu commands. 


This section also applies to commands given using Command-key combinations, which 
are equivalent to menu commands, as defined in the resource file for the application. 


How to do it 


1. Add the cmnu resource to to your applications’s resource compiler input file to add the 
menu command. When you put the command in the resource file, you give the command a 
command number. See the sample programs’ resource files for examples of menu 
commands. 


Important: Menu commands are defined differently for MacApp resource files than for 
the resource files of standard Macintosh applications. MacApp menu resources are 
defined as cmnu resources in the resource input file. The Build command file that 
builds MacApp programs runs the PostRez tool to convert the cmnu resources to 
MENU resources plus the additional information MacApp needs. Therefore, you 
cannot use the resource editor to add menus or menu items and you cannot use DeRez. 
to recreate the original input file.) 


2. In the implementation of your unit, define a constant for the command number you gave 
for the menu command in the resource file. 


3. Override the appropriate DoMenuCommand method. If the command has the same 
effect regardless of which view of the document is active or which view contains the 
selection, then override TDocument.DoMenuCommand for your document. If the 
command is view-specific, override TView.DoMenuCommand for your view. Similarly, 
if the command applies to a particular frame, a window, or the application as a whole, 
override the DoMenuCommand for your descendants of TFrame, TWindow, or 
TApplication. 


MacApp defines a global variable, gTarget, that refers to the event handler that initially 
receives all events, including menu commands. (Views, windows, frames, documents, 
and applications are all event handlers.) MacApp also defines a field of TWindow, , 
fTarget. MacApp automatically sets gTarget to window.fTarget whenever the window is 
activated. (Actually, when the first view is installed in a window, window.fTarget is set to 
that view.) 


In addition, MacApp defines a field TEvtHandler.fNextHandler, which links the event 
handlers in an application in a linked list. 


When MacApp receives a menu event, it passes the event to gTarget. DoMenuCommand. If 


the target cannot handle the command, it calls INHERITED DoMenuCommand. That 
method, usually part of MacApp, first checks if the command is one it can handle and then 
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again calls INHERITED DoMenuCommand. This chain eventually leads to 
TEvtHandier.DoMenuCommand. That method calls fNextHandler. DoMenuCommand. 
The chain continues through the list until the application object is reached. At that point, 
there is no next event handler, and TEvtHandler.DoMenuCommand reports an error. 


See “The Target chain and the cohandler chain” in Chapter 2 for a more complete 
description of how the target chain works. 


Here is the interface for TYourType.DoMenuCommand: - 


FUNCTION TYourType.DoMenuCommand (aCmdNumber: CmdNumber): TCommand; 
OVERRIDE; é 


The form for the implementation is given in the template part of this recipe. 


The template is for the simplest DoMenuCommand method. In this case, an IF statement 
could have been used in place of a CASE statement to create the proper type of command 
object. Whatever structure you use, though, if the command number is not one of yours, 
you must call INHERITED DoMenuCommand so that MacApp can handle its commands. 


If the command changes the document, create a command object and pass the command 
object to MacApp as the return value of DoMenuCommand. If the command does not 
change the document, perform the command immediately and return gNoChanges. 


4. If you return a command object, MacApp calls command.Dolt using the command object 
you return. You should override TCommand.Dolt to execute your command. If the 
command changes the document, you should also override TCommand.Undolt and 
TCommand.Redolt (see the “Undo” recipe). 


Template 


FUNCTION TYourType.DoMenuCommand{aCmdNumber: CmdNumber): TCommand; 
BEGIN 
CASE aCmdNumber OF 
{Here give one of your command numbers}: 
BEGIN 
{Here create and initialize an appropriate command object, or, 
if there are no changes to the document, do the command. } 
DoMenuCommand := {your command object or gNoChanges}; 
END; 
OTHERWISE 
DoMenuCommand := INHERITED DoMenuCommand (aCmdNumber) 
END; 
END; 
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Changing menu appearance and function 


Purpose 


You need to change menu appearance and function to 
e disable a menu command (draw the text in gray) 
© enable a menu command (draw the text in black) 
+ add or remove a check mark (usually for a toggle command) 


e change the text of a command (either for a toggle command, such as when you 
change Undo to Redo, or for a more variable command) 


e add or remove a menu 
e add or remove a menu command from a menu 
e change the font style of a menu command 


How to do it 


1. Every application that defines its own menu commands must override DoSetUpMenus. 
Whenever a mouse-down event is detected in the menu bar, DoSetupMenus is called for the 
application, document, window, frame, and view before the menus are displayed. You can 
override any or all of those DoSetUpMenus methods to change the text for any menu item 
or to enable, disable, or check menu items. You must Gernas DoSetUpMenus for any 
object type for which you override DoMenuCommand. 


Note: MacApp actually calls DoSetUpMenus only when some change has 
occurred. As well as calling DoSetUpMenus before displaying a menu, MacApp 
calls after processing each event. Therefore, the user usually does not have to wait 
for DoSetUpMenus to execute before seeing a menu. 


Begin your override method with INHERITED DoSetUpMenus. You then call the 
MacApp and Menu Manager routines described in the rest of this recipe to change the 
appearance of the menus. 


Although MacApp has global procedures for the most common menu operations, you must 
use Menu Manager routines for much of what is described in this recipe. Menu Manager 
routines use menu handles, menu ID’s, and item ID’s to refer to menus and commands. 
Convert the command number to a menu handle and item number using the following 
MacApp global procedure: 


PROCEDURE CmdToMenuItem(aCmd: CmdNumber; VAR menu, item: INTEGER); 
This procedure returns the Menu Manager menu and item ID associated with the given 
command number. If you need a menu handle (which you generally need for Menu 
Manager routines) use the following MacApp global function: 


FUNCTION GetResMenu(menuID: INTEGER): MenuHandle; 
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The Menu Manager contains routines that are not discussed here because they are rarely 
used in MacApp programs. See the Menu Manager chapter of Inside Macintosh for 
complete information. 

2. For each command number you handle in DoMenuCommand, call either Enable or 
EnableCheck in a version of DoSetUpMenus defined for the same object type. You must 
enable all commands that you want the user to be able to choose, even if the status of the 
command hasn’t changed since the last tme DoSetUpMenus was called, because all menu 
items start out unchecked and disabled. 


Enabling a command draws the command name in black; disabling it draws the name in 
gray. You enable and disable commands that never have check marks with this procedure: 


PROCEDURE Enable(aCmd: CmdNumber; canDo: BOOLEAN) 


This procedure enables or disables the given command depending on the value of canDo. 
If canDo is FALSE, the command is disabled and is displayed in gray type. 


If a command may have a check mark, use this procedure: 
PROCEDURE EnableCheck(aCmd: CmdNumber; canDo: BOOLEAN; checkIt: BOOLEAN) 


EnableCheck places or removes a check mark next to the menu item, depending on the 
value of checkIt. It also draws the text in gray or black, depending on the value of canDo. 


You do not use Enable or EnableCheck to enable the Paste command. Instead, use 
PROCEDURE CanPaste({aDataType: ResType) 

This procedure tells MacApp what data types you can paste at this point. Call it once for 
each data type you can handle, in inverse order of preference. MacApp checks the 
contents of the Clipboard and enables the Paste command if pasting is possible. See the 
“Paste” recipe for more information. 

3. If you want to change the text of a menu item, you should use the following routine: 
PROCEDURE SetCmdName(aCmd: CmdNumber; menuText:Str25S); 


This routine changes the text of the menu item with command number aCmd to menuText. 


Important: You must never use Menu Manager routines in DoSetUpMenus to take the 
actions performed in steps 3, 4, and 5 of this recipe. 


4. If you want to change the font style of a menu command, printing it in bold, italic, 
subscript, superscript, condensed, or expanded or return it to plain text, use the following 
MacApp global procedure: 

PROCEDURE SetStyle(aCmd: CmdNumber; aStyle: Style) 


This is usually used only for the menu items that change type style. 
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5. Some menus have icons displayed to the left of the item text. If you want to set such an 
icon, use the following MacApp global procedure: _ 

PROCEDURE SetCmdicon(aCmd: CmdNumber; menuIcon: Byte); 


This procedure changes the icon shown in the menu for the menu item with command 
number aCmd to the icon represented by menulcon. 
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Handling negative command numbers 


Purpose 


When you have a menu command that cannot be assigned a command number when you 
write your application or that does not fit into the normal menu structure, your 
DoMenuCommand method receives a negative command number. This happens if you 
have a custom menu such as an iconic menu, if you add menu items using Menu Manager 
routines, or if menu items cannot be determined until run time. It happens most commonly 
with the Font menu, which, because the number of fonts cannot be predetermined, always 
returns negative command numbers. i 


How to do it 


1. Implement DoMenuCommand for the appropriate target, which depends on whether you 
want the command to affect one frame, one view, one window, or the entire application. 
When you have a negative command number, you have two choices: 


e CASE directly on the negative values. The values are equal to (256 * menu + item). 


e Call CmdToMenultem to convert the number to the menu ID and item ID for the item 
the user picked. Then take action depending on those values. 


A sample DoMenuCommand is shown in the templates for this recipe. Note that the 
sample handles only negative command numbers. See the “Creating menu commands” 
recipe for more general information about DoMenuCommand. 


2. Implement DoSetUpMenus for the same target so it handles the menus and menu items 
that return negative command numbers. As with ordinary menu items, you must explicitly 
enable and disable all items and check and uncheck items that may have checks. (All items 
start out disabled and unchecked.) There are several possibilities, depending on your 
application. To enable, disable, or check these custom menu items, use Menu Manager 
routines. 


If you have menus (such as the font menu) in which all items return negative numbers, use 
code that follows the pattern shown in the templates. 


If you have menus that may have some negative command numbers because of menu items 
added by calls to Menu Manager routines while the application is running, use the 
Countltems Menu Manager function (used in the template for DoSetUpMenus in this 
recipe) to find out how many items are actually in the menu. Then, if there are menu items 
that return negative numbers, set up those items in DoSetUpMenus and handle those items 
in DoMenuCommand in the same way shown in the template. 


3. If you are implementing a font menu, you need to use the menu ID and item ID in 
DoMenuCommand to get the font number. The font number is used in calls to SetFont, a 
QuickDraw procedure. To find the font number, use the following code sequence: 


CmdToMenultem(aCmdNumber, menu, item); {MacApp global procedure} 

IF menu = mFont- THEN ; 
BEGIN : 
GetItem(GetResMenu(menu), item, aName); {Menu Manager procedure} 
GetFNum(aName, theFontNumber) ; {Font Manager procedure} 
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END; ° 


The value of mFont (a constant you should define) depends on the order of your menus. 
The variable aName, returned by Getltem, is a value of type STR255. The font number is 
an INTEGER. You should store the number somewhere, and use it to set the font 
whenever you draw text in that font. Note your drawing methods should never assume 
the font (or any other characteristic, for that matter) has been set. If you care what the font 
is, always set it yourself. 


Templates 


PROCEDURE TTarget .DoMenuCommand (aCmdNumber: INTEGER); 
VAR menu, item: INTEGER; 


BEGIN 
IF aCmdNumber < 0 THEN 
BEGIN 
CmdToMenultem(aCmdNumber, menu, item); 
{Take action depending on the menu and item values.} 
END; 
END; 


PROCEDURE TTarget .DoSetUpMenus; ` 
VAR item: INTEGER; {Possibly also fontNumber: INTEGER} 
aName: STR255; 
aMenuHandle: MenuHandle; {a Menu Manager type} 
BEGIN 
{All procedure and function calls are to Menu Manager routines. } 
INHERITED DoSetUpMenus; 
aMenuHandle := GetMHandle (mNumberl); 
{mNumberl is a constant you define. It is the menu ID for a menu 
that only returns negative command numbers. } 
IF aMenuHandle <> NIL THEN 
FOR item := 1 TO CountMItems (aMenuHandle) DO 
BEGIN 
GetItem(aMenuHandle, item, aName) ; 
EnableItem(aMenuHandle, item); {or use DisableItem} 
{If this is a font menu, and the current font number is 
stored in gFont add: 
GetFNum(aName, fontNumber) ; 
CheckItem(aMenuHandle, item, fontNumber = gFont);- } 
END; 
aMenuHandle := GetMHandle (mNumber2) ; ; 
{mNumber2 is a constant you define. It is the menu ID for a 
menu that may have menu items added. The constant 
cRegularItems, used below, is another constant you define which 
defines the number of permanent items in this menu. It is 
assumed here that those menu items are handled by ordinary 
command numbers.Handle the setup for the ordinary menu items in 
the menu here or elsewhere in this method. See the “Changing 
menu appearance and function” recipe for more information. } 
IF CountMItems (aMenuHandle) > cReqularItems THEN 
FOR item := (cRegularItems+1) TO CountMItems (aMenuHandle) DO 
BEGIN 
GetItem(aMenuHandle, item, .aName); 
EnableItem(aMenuHandle, item); {or use DisableItem} 
END; 
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END; 
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Creating filtered commands 
Purpose 


With commands that make large or complex changes to a document it may be inefficient to 
actually make the changes when you may have to undo them later. Instead, you may apply 
a filter to the view. Conceptually, a filter makes the view appear as if the data has actually 
changed, when, in reality, the data set is still as it was. That way, if the user chooses 
Undo, you simply remove the filter and if the user chooses Redo, you apply the filter 
again. You don’t actually change the data (commit the command) until the command can 
no longer be undone. z i 


How to do it 


1. You must somehow record which items in the document’s data set were changed by the 
command. If the items are separate objects, this is usually done with a BOOLEAN flag in 
each object, although some applications maintain a separate list of changed items, probably 
as part of. the view or in the command object. In addition, you need a flag that tells whether 
or not the command is currently in effect. 


2. In Dolt, mark the changed items, and set the flag indicating the changes are in effect. 
Then invalidate the images of the changed items in the view. In the Undolt and Redolt 
methods, set the flag that indicates whether or not the command in in effect, and invalidate 
the item’s images. ; 


3. In the Draw and HighlightSelection methods, check the flags (or list of changed items), 
and appropriately alter the way the data is displayed. Itis easiest to see how this is done if 
the command deletes selected items. In that case, you can simply not draw any items that 
were selected when the command was initally done. In more complex cases, you may call 
a separate drawing method, possibly part of the command object, that draws the changed 
items. 
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Using UPrinting 


Purpose 


The printing unit, UPrinting, provides standard printing sufficient for most applications. 
Its basic use is very simple. This recipe shows how you can use the unit in the simplest 
possible way. See the sample programs for examples of more extensive use of the 
capabilities of UPrinting. 

How to do it 

1. You need to include UPrinting in the USES part at the beginning of your unit. 


2. Define a new local variable, aStdHandler, of the type TStdPrintHandler, for your 
TYourDocument.DoMakeViews method. (You can do this in TYourView.IYourView.) 


3. Insert the three lines shown in the template at the end of your 
TYourDocument.DoMakeViews method. (You can do this in TYourView.YourView.) 


4. Insert the following line in your main program before calling application.Run: 
InitPrinting; 


That initializes UPrinting. 


Template 


New (aStdHandler) ; 


{The next three lines make the view printable} 
FailNIL(aStdHandler) ; 
aStdHandler.IStdPrintHandler(aView, FALSE}; 
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Using UTEView 


Purpose 


The text edit unit, UTEView, implements the text editing features of the Toolbox 
TextEdit package. Using this unit, you can have simple text editing of series of 
characters as long as 32,767 characters. TextEdit capabilities include 


e inserting new text 

e deleting characters that are erased with backspacing 

e translating mouse activity into text selection l 

e implementing the Cut, Copy, and Paste commands and Clipboard support 


See the TextEdit chapter of Inside Macintosh for details of TextEdit’s actions. 


This recipe tells essentially how to implement the SmallEditor sample program. 
You may want to build and run that program to get a better idea of what UTEView 
can do for you. i 


How to do it 
1. Include UTEView in the USES part at the beginning of your unit. 


2. As with any application, you must create your own descendant of TApplication 
and override DoMakeDocument for that type. Here is a sample interface: 


TYourApplication = OBJECT (TApplication) 

FUNCTION TYourApp.DoMakeDocument (itsCmdNumber: CmdNumber): TDocument; 
OVERRIDE; 

END; 


The implementation of DoMakeDocument is similar to any DoMakeDocument 
method. A sample is in the template for this recipe. 


3. Create your own document type. It must have certain fields to hook into 
TextEdit. Here is a sample interface: 


TTextDocument = OBJECT (TDocument) 
fText: Handle; {A handle to the actual text belonging to the 
document } . 
fTEView: TTEView; (The TEView object that manages the text} 
PROCEDURE TTextDocument.ITextDocument; 
PROCEDURE TTextDocument .Free; OVERRIDE; 
PROCEDURE TTextDocument.FreeData; OVERRIDE; 
PROCEDURE TTextDocument .DoNeedDiskSpace (VAR dataForkBytes, 
rsrcForkBytes: LONGINT); OVERRIDE; 
PROCEDURE TTextDocument .DoRead(aRefNum: INTEGER; forPrinting: BOOLEAN); 
OVERRIDE; 
. PROCEDURE TTextDocument .DoWrite(aRefNum: INTEGER); OVERRIDE; 
PROCEDURE TTextDocument .DoMakeViews (forPrinting: BOOLEAN); OVERRIDE; 
PROCEDURE TTextDocument .DoMakeWindows; OVERRIDE; 
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END; 
The implementation of these methods is discussed in the rest of this recipe. 


4. Create a new handle for the text with the IDocument method. You do that with 
the MPW Pascal function NewHandle. At this time, f[TEView, which will later 
hold a reference to the TTEView object that handles the text, is set to NIL. 


5. Provide a FreeData method to get rid of the document’s data when the document 
is reinitialized. You can do that by just setting the handle size to zero. 


6. Provide a Free method. Call DisposHandle(fText) and then call INHERITED 
Free. 


7. Implement DoMakeViews so it makes a TTEView object. 


The view object is central to a UTEView application, because the text edit view is 
what handles the text by communicating with the Toolbox TextEdit package. The 
method’s implementation in the templates is self-explanatory. 


Notice that DoMake Views creates a print handler and thus can be printed (UPninting 
must also be in a USES part for printing to work. See the “Using UPrinting” 
recipe.) 


8. Implement DoMakeWindows. The implementation is shown in the template; it is 
entirely standard. 


9. Implement DoNeedDiskSpace, DoRead, and DoWrite so you can save and 
restore documents. See the sample implementations in the template. Notice the 
failure handler used, HdIDoRead. See the “Failure handling” recipe for more 
information. 


Templates 
FUNCTION TYourApplication.DoMakeDocument (itsCmdNumber: CmdNumber) : 
TDocument ; 
VAR aTextDocument: TTextDocument; 


BEGIN 
New (aTextDocument) ; 
FPailNIL(aTextDocument) ; 
aTextDocument.ITextDocument; 
DoMakeDocument :* aTextDocument; 
END; 


PROCEDURE TTextDocument .ITextDocument; 
BEGIN 
IDocument (kFileType, kSignature, kUsesDataFork, NOT kUsesRsrcFork, 
NOT kDataOpen, NOT kRsrcOpen) ; 
fText := NewHandle(0Q); 
FailNIL(f£Text) ; 
fTEView := NIL; 
END; 


PROCEDURE TlextDocument.Free; OVERRIDE; 
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BEGIN 
IF £Text<>NIL THEN 
DisposHandle (fText); 
END; 


PROCEDURE TTextDocument.FreeData; OVERRIDE; 
BEGIN 

SetHandleSize(fText, 0); 
END; 


PROCEDURE TTextDocument .DoMakeViews (forPrinting: BOOLEAN); 
VAR aTEView: TTEView; 


BEGIN 
New (aTEView) ; 
FailNIL (aTE&View) ; 


aTEView. ITEView ( 


NIL, {parent } 
SELF, {its document} 
fText, {its Text} 


Point(0), {location of its top-left-most point} 
eTyping, {its key-command number} 


10, {10 pixels of margin on each side} 
8, {8 pixels margin at top} 
3 1000, {1000 pixels initial view width -- will be 
adjusted to be width of page later} 
100, {100 pixels initial height -- will be adjusted 


to height-of-content later} 

applFont, {font family to use} 

12, {font size to use} 

{l, {normal Style} 

sizePage, {view width determined (initially) by page- 
width less desired margins} 

sizeVariable, {height determined (initially) by amount of 
text} 

kUnlimited {no limit to number of characters accepted} 


fTEView := aTEView; (Save a reference to the view as a field of 
the document object. } 
END; 


PROCEDURE TTextDocument .DoMakeWindows; 
BEGIN 
FailNil (NewSimpleWindow(kTextWindowRsreID, NOT kDialogWindow, 
kWantHScrollBar, kWantVScrollBar, fTEView)); 
END; 


PROCEDURE TTextDocument .DoNeedDiskSpace (VAR dataForkBytes, 
rsreForkBytes: LONGINT); 
BEGIN 
INHERITED DoNeedDiskSpace (dataForkBytes, rsrcForkBytes) ; 
_dataForkBytes := dataForkBytes + GetHandleSize(fText); 
END; 


PROCEDURE TTextDocument . DoRead (aRefNum: INTEGER; forPrinting: BOOLEAN) ; 


VAR numChars: LONGINT; 
fi: FailiInfo; 
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PROCEDURE HdiDoRead(error: INTEGER; message: LONGINT); 
BEGIN 


SetHandleSize(fText, 9); 


Failure(error, message); 
END; 


BEGIN 
CatchFailures (fi, HdlDoRead) ; 
FailOSErr (GetEOF (aRefNum, numChars) ); 
SetHandleSize(fText, numChars); 
FailMemError); 7 
FailOSErr(FSRead(aRefNum, numChars, fText*)); 
Success (fi); 

END; 


PROCEDURE TTextDocument .DoWrite(aRefNum: INTEGER); 
VAR numChars: LONGINT; 

BEGIN 
numChars := GetHandleSize (fText); 
FailOSErr(FSWrite (aRefNum,. numChars, fText*)); 

END; 
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Using UDialog 


The dialog unit, UDialog, provides an extensive group of capabilities for creating dialog 
boxes and other windows made up of groups of controls (such as radio buttons) and other 
items that can get information from the user. 
The dialog unit provides support for these features: 

e views made up of subviews, called concatenated views 

e views that can take in text and validate the text, called key handlers 


e views that can take in numbers and validate the numbers, called number text 
items 


e groups of radio buttons, called radio clusters 
e- modal dialogs 
e modeless dialogs 
The recipes in this section show how to create simple dialogs. See the sample programs, 


the UDialog documentation in Chapter 10 and the source code for further information. In 
particular, you may find the DemoDialogs sample program helpful. 
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Creating a modeless dialog 


Purpose 


A modeless dialog is similar to an ordinary window, except that the dialog’s window object 
is an instance of TDialogWindow and it’s view is an instance of a TDialogView. Modeless 
dialogs usually exist to obtain some sort of information from the user and any information 
they convey to the user is generally simple. Modeless dialogs can be deactivated just like 
ordinary windows, so the user does not have to respond to them before continuing work 
with the application. F 


How to do it 
1. Include UDialog in the USES part at the beginning of your unit. 


2. Define a method that will display the dialog. This method should be for the object type 
that will issue the command. If the dialog has to do with the operation of the application as 
a whole, the method should belong to TYourApplication, and similarly with your document 
or view. (Because you rarely customize TWindow, this is rarely a window method.) 


The interface of this method can be something like 
PROCEDURE TYourType.PoseModelessDialog; 


The details of the method’s interface depend entirely on the use your application makes of 
the dialog. 


Some applications (those that use the dialog more like an ordinary window) do not have a 
PoseModelessDialog method. Instead, the dialog’s view and window are created in 
DoMakeViews and DoMakeWindows along with the document’s other windows. 


3. In the PoseModelessDialog method, create the dialog view and the dialog window, 
install the controls, set the window title, and launch the window. See the template for 
details. For a discussion of dialog items see the “Using dialog items” recipe. 


Notice that the PoseModelessDialog method opens the dialog window and then completes, 
without waiting for a response from the user. 


4. Create your own descendant of TDialogView. You need to do this so you can override 
TDialogView.DoltemSelected. The interface of your new object type might be 


TYourModelessDialogview = OBJECT (TDialogView) 

FUNCTION TYourModelessDialogView DoItemSelected(anItem: INTEGER; VAR 
handledIt: BOOLEAN; VAR doneWithDialog: BOOLEAN): TCommand: OVERRIDE; 
END; 


Notice that you do not have to override any other methods of TDialogView. 
5. Implement DoltemSelected so it takes an appropriate action or returns a command object 


that will take the action. DoltemSelected serves a purpose similar to DoMenuCommand 
and DoMouseCommand, in that MacApp calls it so your code can take an action depending 
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on a user action. No template is given for this method because it depends so much on your 
application. 


See the Puzzle sample program for an example of this method. (Note that Puzzle creates its 
dialog box in DoMakeWindows instead of in PoseModelessDialog.) 


Template 


PROCEDURE TYourType.PoseModelessDialog; 
CONST kStartTxtItem = 10; 
VAR aDialogView: TDialogView; 
aWindow: TWindow; 
succeeded: BOOLEAN; 
title: Str255; 
BEGIN 
New (aDialogView) ; 
aDialoqView.IDialogView(NIL, NIL, aResourceID, 15 {hook}, 1 {(dflt}, 


FALSE); 
aWindow := aDialogView.MakeOwnWindow (FALSE); {make the parameter 
TRUE if you want 
scrolling} 


aWindow.fOpenInitially := FALSE; 
aWindow.Open; 


Final page 5-70 


MacApp Programmer’ s Guiide Cookbook 


Creating a modal dialog 


Purpose 


A modal dialog requires a response before the user can continue with the application. 
Unlike with modeless dialogs, modal dialogs have no window object. As with modless 
dialogs, the view is an instance of a TDialogView. Modal dialogs usually exist to alert the 
user to some condition and force the user to make some sort of response. Modal dialo gs 
cannot be deactiavated, but can only be dismissed. 


How to do it . 
1. You need to include UDialog in the USES part of your unit. 


2. Define a method that will display the dialog. This method should be for the object type 
that will issue the command. H the dialog has to do with the operation of the application as 
a whole, the method should belong to TYourApplication, and similarly with your document 
or view. (Because you rarely customize TWindow, this is rarely a window method.) 


The interface of this method can be something like 
PROCEDURE TYourType.PoseModalDialog; 


The details of the method’s interface depend entirely onthe use your application makes of 
the dialog. 


3. Implement PoseModalDialog as shown in the template. Note that, unlike with modeless 
dialogs, you do not display the dialog from this method. Instead, after you set up the 
dialog, you call TalkToUser. That method requires a response from the user before 
continuing. TalkToUser repeatedly polls each dialog item in the item list by calling 
dialogitem.DoltemSelected. When one of the items returns the value TRUE for the done 
parameter, TalkToUser returns, giving the item that retumed TRUE as the hitltem. You 
should then interpret the value of the hitItem and the other dialog items to take appropriate 
action (which might, if the user chose Cancel, mean taking no action). 


Template 


PROCEDURE TYourApplication.PoseModalDialog(aCmdNumber: INTEGER) ; 
VAR aDialogView: TDialogView; 
rsrcID: INTEGER; 
hitItem: INTEGER; 
someText: $tr255; 
succeeded: BOOLEAN; 
BEGIN 
New (aDialogView) ; 
aDialogView.IDialogView(NIL, @gModalDialogRecord, aResourceID, il 
{hookItem}, 2 (dfltButton}, TRUE); 
{11 is the 'hook item' the user provides in the dialog item list. 
2 is the item number of the default button in the dialog item list} 
{Initialize the dialog from the resource file} 
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aDialogView.TalkToUser(hititem, StdItemHandling); (Display dialog 
f : and interact with 
user} 
{Check hitItem and other dialog items and react to user action. } 
aDialogView. Free; 
END; 
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Using dialog items 


Purpose 


Every dialog view is made up of a list of dialog items. Dialog items are objects of type 
TDialogitem or its descendants, TKeyHandler, TNumberText, and TRadioCluster. You 
may also define your own descendants of any of these types or of TDialogltem itself. 


Here are the predefined dialog item types from UDialog, and what they are used for: 


e TKeyHandler can take in text of any amount and type. The key handlers are 
stored in a circular list of key handlers in the dialog view, and TDialogView 
automatically moves between the key handlers in response to Tab (forward) 
and Shift-Tab (backward). 


e TNumberText can take in numbers. (Any characters other than 0 throu gh9 
are ignored.) It can validate the numbers to make certain they are within a 
given range. 


> TRadioCluster is a cluster of radio buttons. Radio buttons are small circular 
buttons grouped together in a cluster. One and only one member of a cluster 
can be selected ata time. ` 


The number and position of dialog items in the dialog view is defined in the dialog’s 
template in the resource file. 
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The Clipboard 


Purpose 


The Clipboard and the desk scrap are the Macintosh’s standard mechanisms for copying 
and pasting selections within or between applications and desk accessories. 


MacApp maintains a private scrap for the running application, so when you cut or copy 
information from a document, the information is placed in the Clipboard in a form 
particular to the application. The Clipboard window is represented by the TWindow object 
referred to by gClipWindow. The Clipboard view is shown in gClipFrame. 


When the user cuts or copies data from your application, your application creates a view to 
display, and possibly otherwise handle, the data. Normally, that view is of the same view 
type as the one that originally displayed the data. That data, local to your application (and 
typically stored in objects) is in your application’s private scrap. 


When your application begins running, the desk scrap contains data from the last cut or 
copy operation. (The desk scrap will be empty if there has been no cut or copy operation 
since the Macintosh started up.) This is the public scrap, and the data it contains is in one 
or both of two forms common to most Macintosh applications: TEXT (ASCH strings) or 
PICT (a.QuickDraw picture). It may also contain data in the form preferred by your 
application, if that data was cut or copied from a previous instance of your application or 
another application that uses compatible data types. When it is time to display the l 
Clipboard and the desk scrap contains no private scrap yet, you can create a view of one 
your application’s types (typically because there is data in a form used by your application), 
or you can allow MacApp to create a view that will display the common data types. 


When you leave the application, your application gets a chance to convert the information in 
your private scrap to the two common forms. (Leaving the application can mean quitting, 
using the Switcher, or starting a desk accessory.) 


See the Scrap Manager chapter of /nside Macintosh for more information on the desk scrap 
and the Clipboard. , 


How to do it 


Clipboard support implies support of the Cut, Copy, and Paste commands. The l 
implementations of those commands are described under “Standard editing commands” in 
this chapter. This recipe implements only the Clipboard support necessary for those 
commands. 


In particular, this recipe largely deals with what is required of a Clipboard view. The view 
is the main controlling object. The Clipboard view is created in one of two ways. First, 
when the application starts up, a view is created to handle the initial contents of the 
Clipboard, as taken from the public scrap. Second, when data is cut or copied from your 
application, a view of some type originating in your application must be created. In either 
case, the view must be able to handle certain calls from other methods. This recipe deals 
with those calls. 
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Commonly, Clipboard views have documents to handle the data they show. However, that 
is not required. A view showing the desk scrap, for example, may simply read and display 
the desk scrap directly. In implementing Cut and Copy, however, the most common 
Situation is that the data the user has cut or copied is handled by instances of the same 
objects that handled them in the application itself: document, view, and data objects. The 
methods described here are typically implemented for any view types that can have data cut 
or copied, because instances of those view types may be Clipboard views. 


1. Define a handle type for your Clipboard data type by declaring two pointers. For 
example: - 


YourTypeOneClipboard = “PYourTypeOneClipboard; 
PYourTypeOnClipboard = “YourClipType; 


You must create a handle type because the desk scrap cannot use object-oriented data 
structures. Instead, it uses handles to ordinary Pascal data structures. Also, a sin gle 
handle thus refers to all the data of a particular type in the Clipboard. 


As with the data structure created to save your data in a file, the details of your Clipboard 
structure depend entirely on your application. (You can use a common structure to save 
data in a file and to write to the desk scrap, although you'll probably want to add fields 
when saving to a file so you can save state information.) 


2. Define a resource type for your Clipboard data type. The value is an arbitrary four-letter 
string, usually stored in a constant (kClipDataType in the template). Unless your 
information is of the same type used by other applications, you should make this string 

- unique, as it is used to identify data in the public scrap as data your application can 
understand. If the Clipboard information is simply a sequence of ASCII characters, 
kClipDataType should be TEXT; if the Clipboard information is a QuickDraw picture (a 
saved sequence of drawing commands), kClipDataType should be PICT. If you have a 
number of different possible Clipboard data types, define several constants. You should 
register the type identifiers you've chosen with Developer Technical Support to prevent 
duplication. 


3. You don’t have to do anything to display PICT or TEXT data from the public scrap. 
MacApp automatically creates an object of type TDeskScrapView when necessary. If you 
want to be able to display the public scrap data in your own type of view (usually because 
the data is of some type preferred by your application), override 

Make ViewForAlienClipboard for your application type. The interface for that method is 


FUNCTION TYourApplication.MakeViewForAlienClipboard: TView; OVERRIDE; 


In the implementation of this method, call GetScrap (a Scrap Manager routine) once for 
each Clipboard data type you can handle.. (GetScrap takes a handle for the data. Pass NIL 
in this case, because you don’t need to actually read the data now.) If you find data of one 
-of your types, create an appropriate view object, and return it. If you don’t find one of 
your types, call INHERITED MakeViewForA lienClipboard so the MacApp method can 
create and return a TDeskScrap View object. 


You need to override this method only if you need to display data of your type. A 


TDeskScrap View view will correctly pass pasted data of your type to your application even 
if you don’t create a Clipboard view to display the data. 
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A sample implementation is given in the templates for this recipe. The sample begins with 
a call to GetScrap. The first parameter of GetScrap is ordinarily a handle used as the 
destination of the scrap data. In the templates, the destination is NIL, so nothing is passed 
to the application. When display of the Clipboard is required, MacApp calls 

clip YourView.AboutToDraw before calling clipYourView.Draw. AboutToDraw can get 
the information from the scrap and, if necessary, convert it to your document’s data types. 
(The implementation of AboutToDraw is discussed later in this recipe.) Other methods are 
called to read the scrap for pasting. 


4. Override the necessary methods for your Clipboard view type as shown: 


PROCEDURE TYourView.AboutToDraw; OVERRIDE; 

FUNCTION TYourView.ContainsClipType(aType: ResType): BOOLEAN; OVERRIDE; 

FUNCTION TYourView.GivePasteData(aDataHandle: Handle; dataType: 
ResType): LONGINT; OVERRIDE; 

PROCEDURE TYourView.WriteToDeskScrap; OVERRIDE; 


The implementations are discussed in the following steps. 


5. AboutToDraw is provided so you can defer time-consuming actions until you know they 
are actually needed. In particular, if the Clipboard contents need to be read from the desk 
scrap and converted to an application view, you generally do it in this method. 


6. ContainsClipType is called by other methods to find out whether the Clipboard contains 
a particular type of data, The default implementation (as defined in TView) calls GetScrap 
to find out if the requested type is in the public scrap. You should override this method 
when the Clipboard shows the private scrap. (Note that that is always the case when the 
data in the Clipboard got there through a cut or copy in this instance of your application.) 


The interface of this method is 


TYourView.ContainsClipType(dataType: ResType): BOOLEAN; OVERRIDE; 


A sample is given in the templates. 


7. GivePasteData is called to get data from the Clipboard. If you want to get data from the 
public scrap, you don’t have to override this (it is declared and implemented for TView). If 
the data to be pasted is in your application’s private scrap, you need to override this 
method. Its interface is 


TYourView.GivePasteData(aDataHandle: Handle; dataType: ResType): 
LONGINT; 


GivePasteData has two purposes. First, it returns the length of the data of the given 
resource type, in bytes (or, if there is some problem, returns a negative number, which is 
an error code). Second, if aDataHandle is not NIL, the method places the data in the space 
referred to by the handle. 


Your version of GivePasteData should follow this logic: 


a. Check if the data type requested matches the data types your program can handle. 
This should always be TRUE (because the request comes from one of your paste 
methods). If it is not TRUE, return noTypeEn, a predefined constant. 
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b. Ifthe data has been written to the desk scrap, call INHERITED GivePasteData. 
TView.GivePasteData uses GetScrap to put the information in the handle. 


c. Otherwise, the data in the Clipboard originated from your application, and you must 
extract the required information. 


A sample of this method is given in the templates. 


8. To enable other programs to receive Clipboard data from your application, override 

TView. WriteToDeskScrap (which has no parameters) for your Clipboard view. 

(Generally, the Clipboard view is of the same type as your ordinary application view; it 

becomes a Clipboard view when an instance is created to display the Clipboard. Therefore 

you usually need to override WriteToDeskScrap for every customization of TView in your 
` application has that allows a cut or copy operation.) 


When your application terminates or the user uses the Switcher or starts a desk accessory, 
WniteToDeskScrap is called to convert the Clipboard’s contents to the desk scrap. 


See the Scrap Manager chapter of Inside Macintosh for details of writing data to the scrap. 


After you write the data in your application’s preferred type, you should, if possible, write 
itas PICT or TEXT data, or both. 


If the view’s field fWouldMakePICTScrap is TRUE (the default), MacApp will create 
PICT type scrap automatically. You just need to call INHERITED. WniteToDeskScrap 
from your WriteToDeskScrap method. 


9. If you want to have a Clipboard document, create it before making the Clipbaord view. 
When you call TYourDocument.YourDocument, you can pass in TRUE to indicate to 
TYourDocument that you are creating a Clipboard document, althou gh that may not matter 
to TYourDocument. (You do not have to have a Clipboard document, although applications 
usually do.) 


10, TView.FreeFromClipboard frees the view. If you have additional data structures that 
must be freed, you must override FreeFromClipboard. The interface is 


TYourView.FreeFromClipboard; OVERRIDE; 


The default version assumes that you have no document that must be freed. If you have a 
document for your Clipboard, you should call document.FreeFromClipboard (which has 
no parameters) in your version of TYourView.FreeFromClipboard. The TDocument 
version of that method calls ShallowFree, so the Clipboard window is not freed. If there 
are additional data structures (aside from the document object itself) controlled by the 
document that must be freed when the document is freed, also override the TDocument 
version of FreeFromClipboard. 
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11. You need to have a number of items for the Clipboard in the resource file. These are 
included in the standard resource include files provided in the MacApp package. You must 
have ; 


¢ a definition for the Clipboard window in the resource file (this is a resource of type 
WIND with resource ID 200) 


e the Show Clipboard menu item 
> the buzzword strings 'show Clipboard’ and "Hide Clipboard’ 


See the sample programs’ resource files for how you can get these automatically. 


Templates 


FUNCTION TYourApplication.MakeViewForAlienClipboard: TView; 
VAR : 
offset: LONGINT; 
cGlipYourView: TYourView; 
aHandle: Handle; 
elipDoc: TYourDocument; 
BEGIN 
IF GetScrap(NIL, kClipDocType, offset) > 0 THEN (Test whether your 
preferred data type is in the 
scrap. If you can understand 
other types, test for them here} 
_ BEGIN 
New (clipDoc) ; 
clipDoc.IYourDocument (TRUE); {The TRUE is only needed if 
TYourDocument cares if this is a 
clipboard document. } 
New (clipYourView) ; 
clipYourView. TYourView(clipDoc) ; 
WITH clipYourView DO 
BEGIN 
fInformBeforeDraw := TRUE; {Tells MacApp to call AboutToDraw 
before calling Draw. } 
fWrittenToDeskScap :* TRUE; {Tells MacApp it is not 
necessary to write this view to 
the desk scrap if the application 
quits because the Clipboard view 
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was derived from data in the desk 
Scrap. } 
END; 
MakeViewForAlienClipboard := clipYourView; 
END 
ELSE l 
MakeViewForAlienClipboard := INHERITED MakeViewForAlienClipboard; 
END; 


FUNCTION TYourView.ContainsClipType (aType: ResType): BOOLEAN; 
BEGIN = 
ContainsClipType :=°(aType = kYourClipType) ; 
END; i 


FUNCTION TYourView.GivePasteData(aDataHandle; Handle; dataType: 
ResType): LONGINT; 
VAR 
aSize: LONGINT; 
err: OSErr; 
BEGIN 
{The following test checks if the requested data type is your 
program’s type. You may have several types, in which case this 
would be a multiple test.} 
IF dataType <> kYourClipDataType THEN 
GivePasteData := noTypeErr 
ELSE 
IF fWrittenToDeskScrap THEN 
GivePasteData := INHERITED GivePasteData (aDataHandle, 


dataType) 
ELSE 

BEGIN 
{Copy the data in the Clipboard and accumulate the size in 
aSize. If aDataHandle is not NIL, then by exit time, its 
size must be equal to the ultimate value of aSize and the 
Clipboard data must be in the data area referred to by 
aDataHandle.} 

GivePasteData := aSize; 

END; 


END; 
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Purpose 


Any time you access devices, failures may occur. In addition, unanticipated code problems 
may cause failures. MacApp includes a failure-handling mechanism that is intended to 
allow applications to clean up debris left by the failure and continue running from the point 
before the failure. You can also use it to display alerts for the user. 

This recipe, unlike the others, is more descriptive than prescriptive. The failure-handling 
mechanism is really a set of routines that you can call, along with routines that you write, in 
order to provide minimally disruptive handling of failures. This recipe describes the 
architecture of the mechanism and tells how each routine can be used. See the sample 
programs for specific examples of failure handling. 


How to do it 


The failure handling mechanism is built around exception handlers. An exception 
handler is a routine, generally local to some method, that is called when a failure occurs, 
and takes action to handle the failure. See the sample programs for examples of exception 
handlers. 


References to exception handlers are kept on a stack. When an error is likely to occur 
(generally because of I/O or memory allocation) and cleanup needs to be done, MacApp 
posts exception handlers to the stack; application routines should post exception handlers 
when an error the application should handle might occur. (Applications post exception 
handlers sometimes because an error MacApp can’t anticipate may occur and sometimes in 
order to supplement the MacApp exception handler with application-specific action.) 


Whenever a failure occurs, the Failure global procedure is called. Failure is never called 
automatically. You must check for a failure, and call Failure when you find thar it is 
needed. That check is most often done by calling the MacApp global procedures FailNil, 
FailOSErr, FailMemEnrror, or FailResError, which check for specific kinds of errors. Here 
is the interface to Failure: 


PROCEDURE Failure(error: INTEGER; message: LONGINT); 


Failure pops the handler at the top of the stack and calls it. That handler generally does any 
cleaning up it can do (such as freeing temporary objects or handles), possibly sets up the 
error alert, and often calls Failure again to invoke the next handler on the stack. 


1. The exception handlers MacApp posts handle errors in a generalized way, usually by 
displaying an alert telling the user what happened (to the best of MacApp’s ability to tell) 
and then branching around the code that caused the error. (That generally means 
abandoning the command that resulted inthe error.) When an error that MacApp can 
anticipate may occur, you may want to post your own exception handler to set up your own 
alert or to handle the failure in your own way. The mechanism allows you to take the 
action you want, set up certain values to produce a useful message, and then invoke 
MacApp’s event handler. You should always post your own exception handler when a 
failure that MacApp can’t anticipate is possible. 
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An important part of the failure-handling mechanism is the ability to give the user a useful 
alert message. MacApp provides several ways to do that, all working through the same 
routines. When a failure occurs, the exception handler that is initially called (which may be 
a MacApp or an application handler) usually calls Failure to invoke another failure handler. 
Failure’s error and message parameters are used to build the alert that informs the user of 
the error. Handlers usually set those values only if the method that called Failure hasn’t set 
them. (In other words, handlers should assume that the routine that called Failure has more 
specific knowledge about the error, and thus, if it gave values for error and message, those 
are the most appropriate values.) Typically, there is a chain of Failure calls that leads to an 
exception handler (defined by MacApp) that calls TApplication.ShowErors. (If you want 
to change what happens next, you can override ShowErrors.) ShowErrors calls the global - 
routine ErrorAlert. ErrorAlert builds the alert message in different ways depending on the 
message value that you passed. The standard alert strings defined in the standard resource 
files are 


phGenError = could not 42, because ^0. “1. 
phCmdErr = could not complete the “42” command because 40. “1. 
phUnknownErr = could not complete your request because 40. 41. 


The alert string is chosen and the place holders “0, 41, and 42 are filled by ErrorAlert 
based on the error and message values that are passed to Failure. MacApp uses the error 
parameter to Failure to find a string to replace ^0. That string identifies the kind of error 
that occurred. It also uses the error value to find a string to replace “1, if appropriate. “1 
is used for a string that gives the user advice on what to do and is only given if that isn’t 
clear from the error identifier. 


The message parameter of Failure determines what replaces ^2 and what alert is used. 
The message parameter is a LONGINT that is treated as a fixed-point number. The first 
integer, or high word, of a message determines how the second integer, or low word, is 
interpreted. There are five possibilites: 


e If the high word is equal to msgCmdEn, the low word is a command 
number. ErrorAlert translates that command number to a command name, and 
substitutes that for ^2. The phCmdErr alert is used. 


e Ifthe high word is equal to msgAlert, the low word is an alert number (that 
is, a resource number). This generally is an alert that you have defined. That 
alert is then displayed. 


° If the high word is equal to msgLookup, the low word is a positive integer 
that is an index into an operation table in the resource file. This is rarely used. 


e If the high word is not any of those values, it is a resource ID for a string list 
and the low word is an index into that list. This string is then substituted for 
^2. The phGenErr alert is used. 


° If message is equal to 0, the phUnknownErr alert is used. 
2. There are two global routines provided to post exception handlers to the stack and 
remove them when the chance for failure is past: CatchFailures and Sucess. The interface 
to CatchFailures is 


PROCEDURE CatchFailures(VAR fi: FailInfo; PROCEDURE Handler(e: INTEGER; 
m: LONGINT):; 
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The fi parameter is a variable of type FailInfo that you must provide. You don’t have to set 
it to anything. 

Call CatchFailures to set up an exception handler. This pushes your handler onto a stack of 
exception handlers. If MacApp has already pushed a handler on the stack, yours is above 
it, so a call to Failure results in a call to your handler. The interface to success is 


PROCEDURE Success(VAR fi: Failinfo); 


The fi parameter is a variable of type FailInfo that you must provide. You don’t have to set 
it to anything. = 


Success removes your handler from the stack. __ 

Any calls to Failure within the limits of the CatchFailures and subsequent Success calls 
result in the execution of your exception handler. If a routine calls CatchFailures, it must 
call Success (unless there was an error). Also, you must not call Success unless you called 
CatchFailures earlier in the same routine. 

3. You usually don’t call Failure directly. Instead, you use one of the four global routines 
that are provided to test for different kinds of errors: FailNIL, FailOSErr, FailMemEn, or 
FailReésErr. In each case, they call Failure with appropriate error and message values if a 
failure occured. Ifa failure did not occur, they simply return. 

The interface to FailNIL is 

PROCEDURE FailNIL(p: UNIV Ptr); 

The p parameter is any pointer or handle (including object references). 


This procedure tests if the given pointer (or handle) is NIL, and calls Failure(memFullEr, 
0) if it is. 


The interface to FailOSErr is 
PROCEDURE FaildOSErr(error: INTEGER); 


The error parameter is an OS error code, presumably returned by an /nside Macintosh or 
language routine. 


This procedure checks if the given OS error code signals an error and, if it does, calls 
Failure. This is most often used with functions whose return value is an error code, and 
you use it with a statement like: 

FailOSErr (functionCall (parameters) ); 

The interface to FailMemeEnrror is 

PROCEDURE FailMemError; 

This procedure checks if there was a memory error and, if there was, calls Failure. You 


generally call this after you attempt to allocate a new object. It tests the value of MemError. 
If MemError <> noEr then Failure(MemError, 0). 
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4. In your exception handler, you usually want to set the message parameter only if it has 


not already been set. To do that, you can use the global procedure FailNewMessage in 
place of Failure. 


PROCEDURE FailNewMessage(error: INTEGER; oldMessage, newMessage: 
LONGINT) ; 


This procedure calls Failure and passes the error and newMessage or oldMessage 
parameters. FailNewMessage passes the oldMessage parameter to Failure unless it is 0, in 
which case newMessage is passed. This is used in an error handler so the error handler 
can provide a message (newMessage) only if a message was not provided already. You 
would use this routine instead of calling Failure, when you want to set the message value 
but do not want to override a message valué established by a lower-level handler. 
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Chapter 6 
Object-Oriented Assembly Language 


The MPW package includes a library of MPW assembly language macros. The macros 
permit you to write applications, or parts of applications, in an object-oriented fashion 
using assembly language. The MacApp package includes a file that provides an MPW 
assembly language interface for the MacApp units so you can customize MacApp object 
types and implement methods of the descendants in assembly language. 


Object-oriented assembly language allows you to 
e create descendants of object types defined in Object Pascal 
e call methods written in Object Pascal from assembly language code 
¢ call methods written in assembly language from Object Pascal 
Object-oriented assembly language, like Object Pascal, is as much a style of programming 


as a language. This chapter describes the macros provided and includes a sample program 
that uses those macros. 


Although you can write complete MacApp applications in assembly language, it is expected 
that few programmers will choose to do so. These macros are provided primarily so that 
you can write frequently used parts of your program in assembly language, where the cost 
of the extra time to program the assembly language code will be offset by significant 
improvements in performance. 


Important: This chapter does not cover MPW Assembler and is not intended to teach 
how to write 68000 assembly language code. In particular, MPW Assembler defines 
an extensive macro language. This chapter assumes you are familar with it. See the 


Macintosh Programmer's Workshop Assembler Reference for more information on 
MPW Assembler. 


Object-oriented macros 


A group of MPW assembly language macros for object-oriented assembly language 
programming are discussed in the following sections. 

InitObjects 

InitObjects is a macro defined in ObjMacros.a (an MPW shell file) that must be called at the 
beginning of every program written only in assembly language using objects. In other 
words, this must be the first line of every object-oriented assembly language program that 
isn’t linked with an Object Pascal program. 

InitObjects Prototype Statement 


InitObjects 
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Example 


InitObjects 


ObjectDef 


The ObjectDef macro allows you to define object types in object-oriented assembly 
language programs. The ObjectDef macro also generates code so method calls are handled 
properly. 2 
The ObjectDef macro sets up assembly language record definitions so that you can later 
- refer to fields of objects by using %Typename and the field name. For example, if an 
object has this definition 


ObjectDef TArc,TShape, \ 


(nextShape, TShape), \ 
(arcAngle, 2), \ 
METHODS, \ 
(Draw) 


you can use a statement like this 
MOVE.W %TArc.arcAngle(A0) ,-(SP) 


A percent sign (%) is appended to the object-type identifier (other than when used in the 
ObjectDef and ObjectWith macros) so that you can use the Object Pascal object-type 
identifier in a EQU statement to define the size of an object and then use that name in place 
of the size for a field that refers to an object of that type. For example: 


TShape EQU 4 
was used to set the value of the identifier TShape for the above ObjectDef. 
Note: Because an object reference is a handle, the EQU value will always be 4. 


Unlike in Object Pascal, in object-oriented assembly language you must qualify the field 
name by the name of the object type that defined it. For example, if TArc inherits the field 
fColor from TShape, %TArce.fColor would be undefined. You would have to call it 
%TShape.fColor. The ObjectWith macro (described below) is provided to get around this 
problem. 


ObjectDef Prototype Statement 


ObjectDef &TypeName, &Heritage(,FieldList} [,METHODS, MethodList] 


Important: The part of the prototype statement for ObjectDef that is in square brackets 
is optional. The placeholder FieldList should be replaced by a list of all fields of the 
object type, with a size for each field as shown in the examples. The placeholder 
MethodList, similarly, should be replaced by a list of the methods of the object type. If 
you have a method list, the word METHODS must be present. Otherwise, it should 
never be present. 


Final page 6-2 


MacApp Programmer’ s Guide Object-Oriented Assembly Language 


Examples 


ObjectDef Shape, TObject, 
(boundRect, 8), 
(borderThickness,2), 
(color,2), 

METHODS, 
(Draw), 
{(MoveBy), 
(Stretch) 


aed 


ObjectDef Arc, Shape, 
(startAngle,2), 
(arcAngle,2), 
METHODS, 

(Draw, OVERRIDE}, 
{GetArea), 
(SetArcAngle) 


Mo LL 


The numbers given after the field identifiers give the size, in bytes, of the storage required. 


Note: The backslash (\) is required by the MPW Assembler when you continue a. 
statement from one line to the next. 


Important: If a method is inherited and reimplemented, you must qualify the method 
name with the word OVERRIDE as shown for the Draw method. 


ObjectIntf and the IMPL Keyword 


Objectintf is used to create an interface in assembly language for an object type that is 
declared in Object Pascal. It is the same as ObjectDef except that it does not generate 
method tables. 


This macro is generally used when you want to have an assembly-language implementation 
of a method declared in an Object Pascal unit. It allows you to specify which methods will 
be implemented in assembly language. In the Object Pascal unit, you should declare the 
method EXTERNAL. For example, 


-TFoo = OBJECT (TObject) 
fieldl: INTEGER; 
PROCEDURE TFoo.Methl; 
PROCEDURE TFoo.Meth2; 
END; 

IMPLEMENTATION 

PROCEDURE TFoo.Methl; EXTERNAL; 

PROCEDURE TFoo.Meth2; 

BEGIN 


END; 


In the assemblyfile, you need to supply an ObjectIntf template for the object type. You 
must give the entire object-type declaration in the Objectintf template and define the entire 
hierarchy down to the type you use. You give the IMPL keyword, preceded by a comma, 
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after any method you want to implement in awwmbly language. The “Examples” 
subsection below gives the corresponding assembly language declaration for the Object 
Pascal declaration given above.’ 


If the method for which you are providing an assembly-language implementation is an 
override of an inherited method you must specify both OVERRIDE and IMPL: 


ObjectIn£f MyShape, Shape \ 


(Draw, OVERRIDE, IMPL), 


A a a a aa 


ObjectIntf Prototype Statement 


ObjectIntf sTypeName, &Heritage[,FieldList] [,METHODS,MethodList] 


Important: The part of the prototype statement for Objectintf that is in square brackets 

is optional. The placeholder FieldList should be replaced by a list of all fields of the 
object type, with a size for each field as shown in the examples. The placeholder 
MethodList, similarly, should be replaced by a list of the methods of the object type. If 
you have a method list, the word METHODS must be present. Otherwise, it should 
never be present. l 


Examples 


ObjectInt£ TFoo, TObject, 
(fieldl, 2), 
METHODS, 

(Methi, IMPL) r 
(Meth2) 


ee 


Meth] ProcMethOft TFoo 
<code> 
EndMethod 


: The following creates an assembly-language interface for TObject 
; It is avaliable in file ObjMacros.a and is reproduced here. 


Objectin£f TObject,, 
METHODS, 
(Free), 
(ShallowFree), 
(Clone), 
(ShallowClone) 


E a ar ie 
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ObjectWith and EndObjectWith 


These macros allow you to specify a field of an object without having to qualify it with the 
object reference, 


As noted before, you must normally qualify the name of an inherited field with the name of 
the object type that defined it. These macros allow you to avoid that. ObjectWith inserts a 
series of MPW assembly language WITH directives, one for each ancestor object type, so 
you can specify fields of any ancestor object type without qualifying them with the ancestor 
object type name. ObjectWith can be nested. The most recent invocation has precedence 
when there are field name conflicts. You end an ObjectWith block with an EndObjectWith. 


ObjectWith and EndObjectWith Prototype Statements 
ObjectWith &TypeName 


EndObjectWith 


Examples 


ObjectWith Shape 
MOVE.W color({Al),DO 
EndObjectWith 


ObjectWith Arc 

MOVE.W startAngle(Al),-({SP) 
PEA boundRect (Al) 
EndObjectWith 


ProcMethOf, FuncMethOf, and EndMethod 


These macros are used to bracket methods. ProcMethOf and FuncMethOf invoke the 
PROC and FUNC directives. They provide the implicit parameter SELF, which is a 
reference to the object used to call the method. They also invoke the ObjectWith macro 
with the specified type name so that fields of SELF can be accessed without type-name 
qualification. EndMethod invokes the EndObjectWith macro and the ENDPROC directive. 


Important: As with any assembly language routine, before ending the routine (that is, 
before the EndMethod macro) you must remove the parameters from the stack and 


retum to the caller. In a method, you should be careful to also remove the implicit 
parameter SELF. See the sample program at the end of this chapter for examples of 


this. 

ProcMethOf, FuncMethOf, and EndMethod Prototype Statements 
&ProcName ProcMethOf &TypeName 
&ProcName FuncMethof &TypeName 


EndMethod 
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Examples 


Draw ProcMethoOf Shape 


EndMethod 


GetArea FuncMethoOf Arc . 


EndMethod 


MethCall 


MethCall is used to invoke a method. The object that will be SELF must be on top of the 
stack, The type that originally declared the method is needed to make the call unambiguous 
and is provided as the second argument of MethCall. If the second parameter is omitted, 
the current method’s object type is assumed. The MethCall macro generates a JSR to the 
proper method. 


MethCall Prototype Statement 
MethCall &ProcName, éTypeName 


Examples 


MOVE.L A2, ~ (SP) 
MethCall Draw 
MOVE.W DO, -(SP} 
MOVE.W D1, -(SP) 
MOVE. L aShape (A6) , - (SP) 
MethCall MoveBy, Shape 
Inherited 
The Inherited macro calls the method of the given name in the closest ancestor object type 
that implemented that method. Again, SELF must be on top of the stack. 
Inherited Prototype Statement 


Inherited &ProcName 
Example 


‘ MoveSelf -(SP) 
Inherited Draw 
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NewObject 


This macro, as its name suggests, is used to create a new object. It is equivalent to the 
Pascal NEW procedure used with an object reference. 


NewObject generates a JSR to %_OBNEW after pushing the appropriate parameters onto 


the stack. If &Size is omitted (and it usually is) the instance size for the given object type is 
used. The &Loc parameter must be a memory reference. 


NewObject Prototype Statement 


NewObject é&Loc, &TypeName, &Size 


Examples 
NewObject -4(A6é),Are 


NewObject gArray,DynArray, 200 


MoveSelf 
This is a convenience macro. It executes the following statement: 


MOVE.L 8{(A6),&Dest 


MoveSelf assumes that the method began with a LINK A6,#nnnn. (8(A6) is the location 
of SELF when in a method.) 


MoveSelf Prototype Statement 


MoveSelf &Dest 


Examples 
MoveSelf A4 
MoveSelf -({SP} 


MoveSelf aSquare(Aé6é) 
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An object-oriented assembly language sample 
program 


This sample program duplicates the functionality of the PasExample and ObjExample 
Pascal programs shown under “Programs” in Chapter 1. 


PRINT OFF 

INCLUDE ‘QuickEqu.a' 

INCLUDE '‘SysEqu.a' 

INCLUDE '‘ToolEqu.a' 

INCLUDE 'Traps.a' . 

INCLUDE 'ObjMacros.a' ; the macro library for defining objects 
PRINT ON 


Rect EQU 8 
Integer EQU 2 
STR255 EQU 256 
ObjectDef TShape, TObject, \ Define object type TShape, a 
; \ descendant of TObject 
(boundRect, Rect), \ field boundRect occupies 8 bytes 
\ (the size of a Rect) 
METHODS, \ 
(IShape), \ Initialization method 
(RandomRect) , \ Assign a random rectangle to 
\ boundRect 
(Move), \ Assign a different random rect 
(Draw), \ Draw the shape 
(Erase) ; Erase the shape 


ObjectDef TArc,TShape, \ Define object type TArc, 
\ descendant of TShape 

(startAngle, Integer), \ starting angle of the arc 
(arcAngle, Integer), \ degrees in the arc 

METHODS, \ 
(IArc), \ Initialization method for TArc 
(Draw, OVERRIDE), \ Override the Draw method 
(Erase, OVERRIDE) ; Override the Erase method 


ObjectDef TRoundRect,TShape,\ Define TRoundRect, descendant of 
: i \ | TShape 


(ovalWidth, Integer), \ ovalWidth and 
{ovalHeight, Integer), \ ovalHeight define the "roundness" 
METHODS, \ 
(TRoundRect), \ Initialization method for 
\ TRoundRect 
(Draw, OVERRIDE), \ Override the Draw method 


(Erase, OVERRIDE) ; Override the Erase method 


ObjectDef TControl,TObject,\ Define TControl, descendant of 
\ TObject ' ; 
(commandLine, STR255), \ Text displayed in the command line 
{commandBox, Rect), \ Area in which command line 
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\ displayed 
METHODS, \ 
(IControl), \ Initialization 
(Draw), \ Draw the command line 
(Run), \ Run the command loop 
(NewShape) ; Function that returns a TShape 


Lee eee eee RSS SESS RSLS REEL ESAS SLE RSP ESE SSR SRE ESE RE SEE RE RESELL ESA SEES SES) 


x* Record templates and Global Data area hatin 
[eee eee ee eee eh Shee e eee ese Pe SPEER E LESSER RS ESA LE SEE LE LEAS L ES EEE SSeS EE eS 


Point RECORD 


0) Point = RECORD CASE INTEGER OF 

v DS.W 1 ; 1: (v: INTEGER; 
h DS .W 1 ; hh: INTEGER); 

ORG v 
vh DS .W h ; 2: (vh: ARRAY(1..2}] OF INTEGER) 

ENDR 7 END; 
EventRecord RECORD 0 :EventRecord = RECORD 
what DS.W 1 ; what: INTEGER; 
message DS.L i ; message: LONGINT; 
when DS.L 1 ; when: LONGINT; 
where DS.L Point ; where: Point; 
modifiers DS.W 1 7 modifiers: INTEGER 

ENDR ; END; 
GlobalData RECORD 
myPort DS.B portRec : the grafPort 
myEvent DS.L EventRecord ; Current event info 
ctriRect DS.B 8 ; CommandLine rectangle 
gControl DS.L 1 ; The control object 


ENDR 


KKK RRR KH KKK RK KEKE KER KERR KHER KR RK KERR KK kk k k kk KK KKK KKK EK 


tx Program Entry point wx 
Arrt MKKRER ERA RAR RH KK KKK wk kek RRt rak Akk kakker KEKE KKK KKK 


ShapeExample MAIN 


WITH GlobalData ; Cover our data areas 

IMPORT QUICKDRAW: Data 

InitObjects ; Must call this if Main module is in 
; assembler 

PEA QUICKDRAW-4 ; Initialize QuickDraw 

_iInitGraf 

_InitFonts ; Initialize Font Manager 

_initCursor ; Initialize Cursor state 

_HideCursor ; Hide it 

PEA myPort 

_OpenPort ; Open a grafPort for drawing 
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_PenNormal 
PEA 


_EraseRect 


PEA ctrlRect 


emdString 


MOVE.W 
MOVE .W 
MOVE.W 
MOVE.W 
_SetRect 


NewObject 
PEA 


PEA 
MOVE.L 
MethCall 


MOVE.L 
MethCall | 


ShowCursor 


ENDWITH 
RTS 


DC.B 
ENDPROC 
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myPort+portRect (A5} 
3; Clear the screen 


; Set up rectangle for commandLine 
#5,-~(SP) 
#20,-(SP) 
#500,-(SP) 
#60,-(SP) 


gControl, TControl 
emdString 


Create a new TControl object 
Push Initialization 
parameters 


Me No fe 


ctrlRect 
gControl,-(SP) 
IControl,TControl ; Initialize the control 


; object 


gControl,-(SP} 


Run, TControl Run the main loop 


“o 


'R)oundRect, A)rc, M)ove, Q)uit' 


KRRKAKARRRAKKATAKKRKARRAKRAKKKKKKKKKHKKKKREKRKKKKAKKHKRRKKKKKKKKKKKEKKAHKE KKK 


Procedure TShape.IShape; = 
(he SeeeeSLEC REE RES SSS SEE SERS SER ERASE LAL ESE SEE SECO LSS EL SEC RRL SCOPES ESSE LE 2 


kaka g 


IShape 


ProcMethof 


LINK 
MoveSelf 
MethCali 
UNLK 
MOVE.L 
RTS 
EndMethod 


TShape 


A6, #0 

- (SP) 
RandomRect 
A6 


(SP) +, (SP) ;Stuff return address on top of SELF 


RUKH KR KR RRR RRR RK RK KIRKE a aa a a a a a a a ia a a iea a Baa is a o a a a a s a a e a a KR KKK 


Procedure TShape.Draw; 2%. 
(2 oe ee ee eee eee eee eee ee ee eee fee ee SkkaSaEEE ERE SAREE ESR SESE EERE Le eee Ek 


ak 


Draw 


ProcMethoft 


LINK 
UNLK 
MOVE.L 


RTS 
EndMethod 


TShape 


AG, #0 

A6 

(SP) +, (SP) ; stuff return address on top 
; of SELF 
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KKK KM KKK AK K KKK KKK KK KEK ERK KK KKK KHER k kkk k kk kk k k HK KKK KK KKK 


xe Procedure TShape.Erase; pa: 
KKK RRR KKH KKK KK RR KKK REE KKK KKK KEKE KKK KKH REE KKKKKKKKKKKE KEE 


Erase ProcMethoOf TShape 
LINK A6, #0 
UNLK A6 
MOVE .L (SP) +, (SP) ; Stuff return address on top of 
; SELF 
RTS 
EndMethod 


RERKRAKKEKEA KKH HKK KKK KEK KKK KK EEK KKK KKK KEKE KERR KKKKKEKKE KKK KKK 


ball Procedure TShape.Move; A 
REKKRKKEKKK ARK AE RK KR RR KKK RRR KK EKA KKK * 


Move ProcMethOf TShape 
LINK A6, #0 
MoveSelf -(SP) 
MethCall RandomRect 
UNLK A6 
MOVE.L (SP) +, (SP) ; Stuff return address on top of 
; SELF 
RTS 
EndMethod 


RRR KIRK KKK KH KR RRR KKK KKK RRR RR HERRERA K KKK 


Bd Procedure TShape.RandomRect; =* 
RRR KK Ke KR KKK RR RIK KKK KKK krk RRR RRE Ekek kkk kkr 


width EQU 40 ; Width of a shape 
height EQU 40 ; Height of a shape 
minVertPos EQU 75 ; Minimum vertical screen coordinate 


RandomRect ProcMethOf TShape 
LINK A6, #0 


* Assign Random values to left and right coordinates of boundRect 


CLR.W ~ (SP) ; Find random coordinates and size 
; for bounds 
_Random + Get a random number 
MOVE.W (S5SP)+,DO0 
BGE.S @l 
NEG.W DO 
@1 EXT.L DO ; DO now has Abs (Random) 
MOVE.L thePort (A5), A0 
MOVE. L (A0), AQ 
MOVE.W portBoundstright (A0), D1 
SUB. W #width, Dl + Dl <= portBounds.right - width 
DIVS D1,D0 ' 
SWAP DO ; DO <- Abs (Random) MOD Dl 
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' MoveSelf 
MOVE.L 
MOVE.W 


MOVE.W 
ADD.W 


* Assign Random values 
CLR. W 


_Random 
MOVE.W 
BGE.S 
NEG. W 
@2 EXT.L 
MOVE.L 
MOVE.L 
MOVE.W 
SUB. W 
SUB. W 
DIVS 
SWAP 
ADD .W 
MoveSelf 
MOVE.L 
MOVE.W 


MOVE.W 
ADD.W 
UNLK 
MOVE.L 


RTS 
EndMethod 


Al 

(A1), A1 ; Dereference SELF 

DO, left+boundRect (Al) ; Assign boundRect.lefr 

: : ; field 

D0, righttboundRect (Al) ; Assign boundRect.right 
; field 


#width, right+boundRect (Al) 


to top and bottom coordinates of boundRect 

~ (SP) Find random coordinates and size for 
bounds 

Get another random number 


(SP) +,D0 
@2 

DO 

DO 3 DO now has Abs (Random) 
thePort (A5) ,A0 

(AQ), A0 

portBounds+bottom(AQ),D1 


#height,D1 ; D1 <- portBounds.right ~ width 
#minVertPos,D1 


D1,DO 

DO ; BO <- Abs(Random) MOD D1 

#minVertPos,D0 ; Adjust vertical coordinate 

Al 

(Al), Al +; Dereference SELF 

D0, top+boundRect (Al) ; Assign boundRect.left 
; field 

D0, bottom+boundRect (Al) ; Assign boundRect.right 
; field 


#height, bottom+boundRect (Al) 


A6 
(SP) +, (SP) ;Stuff return address on top of SELF 


bia a aaa KK KR KK KERR KEKE KKK HK KEKE KKK 


xx Procedure TArc.IArc; ae 
(SSeS eee eee Pee EE EES SLES E ELE RS SCE SE SL OSC OL OSLO SS ELS LES CSRS SSeS SSS ee ee 


degrees EQU 
IArc ProcMethof 


LINK 
MoveSelf 
MethCall 


CLR.W 


_Random 
MOVE .W 
BGE.S 
NEG.W 
Q1 EXT. L 
DIVS 
SWAP 


Final 


270 

TAre 

A6, #0 

- (SP) 

IShape ; Initialize inherited fields 

~(SP) ; Find random coordinates and size for 
; bounds 
; Get a random number 

{SP} +,D0 

@i 

D0 

DO. ? DO now has Abs (Random) 

#degrees, D0 

DO ?; BO <- Abs (Random) MOD 270 
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@2 


MoveSelf ‘AO 


MOVE.L (A0), A0 ; Dereference self 

MOVE.W DO, startAngie (A0) ; Assign startAngle field 

CLR.W ~(SP) ; Find random coordinates and size for 
; bounds 

_Random ; Get another random number 

. MOVE.W (SP)+,D0 

BGE.S @2 

NEG .W DO 

EXT.L DO f 7 DO now has Abs (Random) 

DIVS #degrees,DO . 

SWAP DO ; DO <- Abs (Random) MOD 270 

MoveSelf AQ 

MOVE.L (A0), A0 ; Dereference self 

MOVE.W DO, arcAngle (A0) ; Assign arcAngle field 

UNLK A6 

MOVE.L (SP)+, (SP) ; Stuff return address on top of 

; SELF 
RTS 
EndMethod 


RRR REIR ER RRR IER KKK KKK KR KK RK RR KERR KEKE RK KEKE KK 


xx 


Procedure TArc.Draw(pat: Pattern); “% 


RARER ERA RM KKK KERR KR RM RRR KEKE KKK EKER KK EEK kkk 


pat 


Draw 


Final 


EQU 12 ; Offset of pat parameter from A6 after 
į the LINK. (Recall SELF is at 8(A6)) 


ProcMethoOf TArc 


LINK A6, #0 
MoveSelf Ao 
MOVE.L (A0), AQ ; Dereference SELF 

Push the four params for the FillAre call 
PEA boundRect (A0) ; Push ref to boundRect 
MOVE.W StartAngle (A0),~-(SP) ; Push startAngle 
MOVE.W arcAngle (AQ),-(SP) ; Push arcAngle 
MOVE.L pat (A6), - (SP) ; Push ref to pattern 
_FillArc 
MoveSelf AO 
MOVE.L (AQ), A0 ai ; dereference SELF 


Now push the three params for the FrameArc call 


PEA boundRect (A0) ; Push ref to boundRect 
MOVE.W startAngle(A0),-(SP) ; Push startAngle 
MOVE.W arcAngle (AQ},~(SP) ; Push arcAngle 
_FrameArc 

UNLK A6 

MOVE.L (SP), A0 ; Load return address 
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ADD .W #12,S5P + Pop return address, pat, and SELF 
JMP (A0) 
EndMethod 


Pee eee Akkkkkkkkkkkkkkkk kikk krk kkkt kkk kkk kkk EES ALA LS eRe SSL SE To 


lkaj Procedure TArc.Erase; ak 
RK KKH RK RK KR HK ARR RRR ERE KEKE RK REM AEARMREK KKK REE kkk RARR k 


Erase ProcMethOf TArc 
LINK AG, #0 t% 
MoveSelf AQ 
MOVE.L (AQ) , Ad ; dereference SELF 
* Push three params for the EraseAre call 
PEA boundRect (A0) ; Push ref to boundRect 
MOVE.W startAngle(A0),-(SP) ; Push startAngle 
MOVE .W arcAngle (A0),-(SP) ? Push arcAngle 
_EraseArc 
UNLK A6 
MOVE.L (SP} +, (SP) ¿Stuff return address on top of SELF 
RTS 
EndMethod 


-S Pe eeRee eee LS RL SRS E SER ESE AREER SESE RE ESLER ELS SS SSS CLC CCL EP PPS PS Sa Se Se E 


** Procedure TRoundRect.IRoundRect; rx 
KEKE KR KRRRRRRRKKRK KKK KH KEK KKK kkk kR RA tkk AREER KARR EKER EK 


IRoundRect ProcMethOf TRoundRect 


LINK A6, #0 
MoveSelf ~(SP) 


MethCall IShape Initialize inherited fields 


Me 


MoveSelf AQ 


MOVE.L (AQ) ,A0 ; Dereference self 

MOVE.W #20, ovalWidth (A0) ; Initialize ovalWidth field 
MOVE.W #15,ovalHeight (AQ); Initialize ovalHeight field 
UNLK A6 

MOVE.L (SP) +, (SP) ; Stuff return address on top of SELF 
RTS 

EndMethod 


RRR EKER REE ER RR KEKE RE HK KHER IRE RK KR EK KERR RK KR RK KEk k kk kkrk kk 


=e Procedure TRoundRect .Draw(pat: Pattern); eae! 
KK KKK KKK KR HK KR KR KKK KR KR KKK REM KERR ERR KKK KKK KR 


Draw ProcMethof TRoundRect 


LINK A6, #0 
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MoveSelf AO 
MOVE.L (AO) ,A0 ; Dereference SELF 
* Push the four params for the FillRoundRect call 
PEA boundRect (A0) 4 Push ref to boundRect 
MOVE.W ovalWidth (A0), -= (SP) ; Push ovalWidth 
MOVE.W ovalHeight (A0),-(SP) ; Push ovalHeight 
MOVE.L pat (A6), =- (SP) ; Push ref to pattern 
_PillRoundRect 
MoveSelft AQ 
MOVE.L (A0), A0 7 ¢ Dereference SELF 
* Now push the three params for the FrameRoundRect call 
PEA boundRect (AQ) ; Push ref to boundRect 
MOVE.W ovalWidth (A0),-(SP) ; Push ovalWidth 
MOVE.W ovalHeight (AQ),=-(SP) ; Push ovalHeight 
_FrameRoundRect 
UNLK A6 
MOVE.L (SP) ,A0 ; Load return address 
ADD .W #12,SP + Pop return address, pat, and SELF 
JMP (A0) 
EndMethod 


Lae ea aE LESSER ESSE SESE RR ESL ASE RES S LESS ESL ESR SER AL EL ELSE RALA SES SR ALE ES 2S SY 


ae Procedure TRoundRect.Erase; . 
[eee ee ee eee eee PARES RARE RARE SS SES SEAS ESLSeSA SES ELE SRR ER AL LS LA LS LESSEE See eo 


ee 


Erase ProcMethoOf TRoundRect 
LINK A6, #0 
MoveSelf AQ 
MOVE.L (A0), A0 ; Dereference SELF 

* -Push three params for the EraseRoundRect call 
PEA boundRect (AQ) "4 Push ref to boundRect 
MOVE.W ovalWidth (A0),-(SP) ; Push ovalWidth 
MOVE.W ovalHeight (AQ) ,-(SP) ; Push ovalHeight 
_EraseRoundRect 
UNLK AG 
MOVE.L (SP)+, (SP) °;Stuff return address on top of SELF 
RTS 
EndMethod 


KRHA KREKRE KEKE KEKE KEKE REKKKEEREKRAKRKEKKERK RRR KRE KKK KHMER EKRHAKKEKKEKEK 


Procedure TControl.IControl(itsLine: S$TR255; itsBox: Rect) ** 


HK HR KKK RRR RK KKK RHR KEKE KARE KKK EKREK KR KEKE KRK KKK EKER KKK 


nx 


16 ; Offset of itsLine parameter from A6 


itsLine EQU 

itsBox EQU 12 ; Offset of itsBox parameter from A6 
IControl ProcMethOf TControl 
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LINK A6, #0 
MoveSelf AO 
MOVE.L (A0), A0 _ 
LEA commandLine {(A0),AQ; Load address of commandLine 
MOVE.L itsLine(A6),Al ; Load address of the string 
MOVEQ #64,D0 
61 MOVE.L {Al} +, (A0) + ; Copy the string 
SUBQ.W #$1,D0 
BGT.S . eL 
MoveSelf AO 
MOVE.L {A0}, A0 
LEA commandBox (A0), A0 ; Load address of commandBox 
MOVE.L itsBox(A6),Ai 7; Load address of the rect 
MOVE.L (Al) +, (AQ) + ; Copy the rect 
MOVE.L (Al) +, (AQ) + 
UNLK : A6 
MOVE.L (SP), A0 ; Load return address 
ADD.W #16,SP; Pop return address and parameters 
JMP ; (AQ) 
EndMethod 


CPSP CLIC SSCL CCL eS CSC CL Heie He He de ie TCS de He de de e e He de Ke e d ee e Re e e A k k R de KEHE R k k A k k R k 


ak Procedure TControl.Draw; ae 
Fee tee ee ee RK KR KK RRR KANE RENEE EREREKKEK KEK 


Draw ProcMethOf TControl 
LINK A6, #0 
MOVE.L a4, = (SP) ; Save A4 
MoveSelf A4 
MOVE.L (A4), A0 + Dereference SELF 
PEA commandBox (A0) 
_EraseRect + Erase the commandLine rectangle 
MOVE.L (A4), A4 : Since MoveTo is heap "safe", 
; we dereference once for 
; both calls 
MOVE.W left+commandBox (A4), -~ (SP) 
MOVE.W bottom+tcornmandBox (A4) ,=(SP) 
_MoveTo + Set up pen location for string 
PEA commandLine (A4) 
_DrawString + Draw commandLine string 
UNLK A6 
MOVE.L (SP) +, (SP) ;Stuff return address on top of SELF 
RTS 


EndMethod 


RERKRKKR KERR RRR KEK KKK KKK RK EKER RRR KR RK KKK KERR KKK KKK 


ex Procedure TControl.Run; Me 
WKH KKK HIKE RRR KH RK KKK KIRK RHR R KKK KKK RK KEKE EKER KEK KKK 
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Run 


loop 


moveľt 


otherwise 


Drawit 


Final 
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ProcMethof TControl 

WITH GlobalData ; Cover our data areas 

IMPORT QUICKDRAW: Data 

LINK A6, #0 

MOVEM.L D7/A3/A4,=-(A7) 

SUB.L A3,A3 3; thisShape <- NIL 

SUB.L A4,A4 ; nextShape <- NIL 

MoveSelf ~ (SP) 

MethcCall Draw ; Draw the command line 

CLR.W - (SP) i 

MOVE.W #8,- (SP) + Push keyDown mask 

PEA myEvent ; Push global event record 
_GetNextEvent ; Ask for next keydown event 
MOVE.B (SP)+,D0 

BEQ.S loop ; Loop back if no event found 
MOVE.L #$FF, D? 

AND.W myEvent .message+2,D7 ; Get typed character 
CMPI.W #'m',D7 ; Check for Move command 
BEQ.S movelt 

CMPI.W #'M',D7 

BNE.S otherwise 

MOVE.L 8&3, D0 

BEQ.S loop 

MOVE.L A3,- (SP) ; Push thisShape 

MethCall Erase, TShape 

MOVE.L A3, ~ (SP) ; Push thisShape 

MethCall Move, TShape 

PEA QUICKDRAW+gray-4 

MOVE.L A3,-(SP) ; Push thisShape 

MethCall Draw, TShape 

BRA.S loop 

CLR.L ~ (SP) ; Make room for new shape 
MOVE.W D7,-(SP) 

MoveSelf - (SP) 

MethCall NewShape ; Create a new shape 

MOVE.L (SP) +, A4 

MOVE.L A4, D0 

BEQ.S endloop ; Character unrecognized by NewShare 
MOVE.L A43, D0 

BEQ.S DrawĪt ; Skip to draw if thisShape is NIL 
MOVE.L A3,-(SP) 

MethCall Erase,  TShape 

MOVE.L A3,-(SP) 

MethCall Free, TObject 

MOVE.L A4,A3 ; ThisShape <~ nextShape 

PEA QUICKDRAW+gray-4 
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endloop 


finished 


MOVE.L 
MethCall 


CMPI.W 
BEQ.S 
CMPI.W 
BNE.S 


MOVEM.L 
UNLK 
MOVE.L 
RTS 
ENDWITH 
EndMethod 
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A3,~(SP) 
Draw, TShape 
#'q',D7 ; If user types q or Q, 
finished 

#'Q',D7 

loop 


we are finished 


{(A7) +,D7/A3/A4 
A6 
(SP)+, (SP) ;Stuff return address on top of SELF 


HR k k eH e ie ke de de ke de de te ke ke de e d ke ke e ie ke e RI e ie de de ke k k k k k k kk k k kk k k 


Function TControl.NewShape(ch: CHAR): TShape;** 


HEHE IK HH THe kk k k I Ie eK KK KR I HT KK KKK RK 


wx 


theNewShape EQU 


ch 


NewShape 


newaArc 


next 


newRRect 


returnNil 


finished 


EQU 
FuncMethoft 
LINK 


MOVE.W 
CMPI.W 
BEQ.S 
CMPI.W 
BNE.S 


NewObject 
MOVE.L 
MethCall 
BRA.S 


CMPI.W 
BEQ.S 
CMPI.W 
BNE.S 


NewObject 
MOVE.L 
MethCall 
BRA.S 


MOVE.L 


14 ; Offset of return value location from A6 
12 ; Offset of ch parameter from A6 
TControl 


A6, #0 


ch(A6),D0 ; BO <- ch 

#'a',DO ; Check for Arc command 
newArc 

#'A',DO 

next 


theNewShape (A6) , TArc ; 
theNewShape (A6) ,- (SP) ; 
IArc, TArc ; 
finished 


Allocate a new Arc 
Push it onto stack 
Initialize it 


#'r',DO ; 
newRRect 

#'R', DO 

returnNil 


for RoundRect command 


theNewShape (A6), TRoundRect ; Allocate a new 
7 RoundRect 
Push it onto stack 


Initialize it 


theNewShape (A6),-(SP) ; 
TRoundRect, TRoundRect ; 
finished 


#0,theNewShape(A6); R eturn NIL if other char 
i typed 


A6 
(SP), AQ 
#10, SP 
(A0) 
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EndMethod 


END 
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Chapter 7 


The Flow of Control in Response to 
Events 


This chapter describes how MacApp handles events. 


Like all Macintosh applications, MacApp applications act in response to events, almost 
always events generated by the user. The possible event types that MacApp applications 
need to deal with are 


e mouse button down 
* menu commands 
° key commands (typing) 
e update 
e network events 
Note that this is not the same list of event types that ordinary Macintosh applications deal 


with. MacApp preprocesses Event Manager events and calls your code only when 
necessary. 


This chapter gives a flow chart for each event. Each chart shows what happens in MacApp 
code and in application code when a particular event occurs. In general, the complete 
behavior of a routine is not shown—only what is involved in handling the event in 
question. 


The first chart is a key for the other charts: it explains how to read the other charts. 


(The original versions of these charts were generated by the Flow sample program, 
included in the sample programs on your source disk. If you want instructions for using 
Flow, see Chapter 3, “Using MacApp.”) 


The methods discussed here are described in Chapter 10, “Object and Method Reference,” 
and the global routines, variables and constants are described in Chapter 9, “Globais.” 
Although opportunities for you to override methods are mentioned in the commentaries, 
Chapter 5, the Cookbook, is where most instructions for writing a MacApp program are 
provided. 
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Demonstration Chart (Figure 7-1) 


Figure 7-1 demonstrates how to read the other charts in this chapter. 


The charts are made up of closed shapes of various kinds. The calls move from the 
outermost level toward the innermost, and from the top to the bottom. Outer boxes call 
inner boxes; inner boxes return to outer boxes when the routines complete. Sometimes, the 
inner boxes hold just explanatory text. (Not all calls are shown; the call sequences are 
sometimes simplified for clarity.) 


Numbers in circles correspond the the numbers in the explanations that accompany each 
chart. In Figure 7-1, the numbers in circles direct you to the following explanatory text: 


1) The outermost routine is usually a method called by some other method. The outermost 
method in each chart is the method that controls everything else that happens. When the 
application is finished responding to the event, control returns to this outermost routine. 


2) FirstRoutine is called by OutermostRoutine. When FirstRoutine completes, control 
. returns to OutermostRoutine, which then calls SecondRoutine. 


3) “Informal conditional” is a condition that determines whether or not SecondRoutine is 
actually called. 


4) Text in a box with two sidebars is explanatory. It usually does not represent a routine. 


5) When the name of a routine is written in italics, the routine is an Inside Macintosh 
routine. (Note that this routine is called by SecondRoutine not by thirdRoutine. 


6) When a routine’s name is written in boldface, it is a routine you implement. Most of 


these routines are discussed in the Cookbook , and the explanatory text for the chart directs 
you to the appropriate recipe. 
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Figure 7-1 
Demonsiration chart 


OutermostRoutine 


FirsfRoutine (2) 


— mida Macintoshkoutine (5) 





koutineYoulmplemen © 
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TApplication.Run igure 7-2) ; 


The main program calls the application object’s Run method after creating and initializing 
the application object. 


1) HandleFinderRequest handles opening a document from the Finder and printing a 
document from the Finder. 


2) If the application was started just to print from the Finder (gFinderPrinting=TRUE), 
then the printing has already been done when the application reaches this point. Otherwise, 
the application needs to be launched fully, which means the menus must be set up and the 
main event loop must be launched. 


3) AboutToLoseControl is called so the application can do whatever it has to do before 
quitting. 
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Final 


Figure 7-2 
TApplication.Run 


gApplication.Run 


HandlefinderRequest ( 1) 





_gApplication.SetuptheMenus | 


gAppiication.MainEventLoop 


T the “Main event loop” chart 
j gAnplication. AbourloloseConirol (3) d 
KEA 
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Main event loop (Figure 7-3) 


The main event loop is the center of any Macintosh application. Most of the time in any 
application is spent in the main event loop. In a MacApp application, the application object 
is created and initialized, the menus are set up, and the method 
gApplication.MainEventLoop is called. (The global variable gApplication holds a reference 
to the application object.) You usually do not override TApplication.MainEventLoop, 
although you can do so, if you want. 

1) This step is only done when the application begins. 


2) This loop is repeated until the user chooses Quit. It begins by calling GetEvent to check . 
the event queue for user or network activity. 


3) PollEvent gets events and handles them. 


4) Idle gives event handlers a chance to do idle-time tasks. The idle phase tells Idle 
whether idling is begining, continuing, or ending. 


5) MacApp uses event information in a different form than that provided by GetNextEvent. 
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Figure 7-3 
The main event loop 


gApplication.MainEventLoop 
| _Set gidlePhase to idle8egin || 
REPEAT the following until gAppOon e=TRUE 
) ac @Application.Pollevent 


Systernfask § 


gApplication.GetEvent 


GetNextEvent § 


If GetEvent returns TRUE 
IF gidlePhase © IdleBegin THEN 


Creme GAPPlication.idietidleEnd) 


{See “Obeying an event” chart | 


iF commandtloPerform <> gNoChanges THEN 
gAppiication.PerormCommand(commandloPerform) 


| See “Performing a command’ chart |] 


if GefNextEvent returns FALSE 


man PPlication.idie(giclePhase) — 
set gidlePhase to idleContinue |] 
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Obeying.an event (Figure 7-4) 
Once an event has been received by TApplication.MainEventLoop, it is passed to 
gApplication.ObeyEvent. (The global variable gApplication holds a reference to the 
application object.) ObeyEvent calls methods which either carry out the command 
(generally only if the command can not be undone) or return a command object. The 
command object is returned to the main event loop, which passes it 
gApplication.PerformCommand. (See the “Performing a command” section.) 
1) The click count is maintained in a global variable, gClickCount. 
2) If the user picks a menu command, gTarget.DoMenuCommand is called. 


3) SetupTheMenus leads to a call to gTarget.DoSetupMenus. This call is only made if an 
event has occured since the menus were last set up. 


4) A mouse press in the view eventually leads to a call to TYourView.DoMouseCommand, 
which handles the action. 


5) UpdateEvent leads to a call 6 TYourView.Draw, 

6) CommandKey translates the key combination into a menu command. 
7) DoKeyCommand is meant to handle typing. 

8) HandleAlienEvent allows the application to handle foreign events via 


TYourA pplication. DoHandleEvent. A foreign or alien event is an event such as a network 
event that comes from outside the application. 
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Figure 7-4 
Obeying an event 


gAppiication.ObeyEvent 
CASE on the event type 
mouseup 


| Keep track of click count _ Ki) 


CASE whereMouseDown OF 
inMenuBar 


SetupTheMenus (3) 


commandlorertorm := Menutvent 


|| See “Choose a menu command” chart 


insysWindow 
M gApplication AbouttoLosecontrol 
SystamClick 


| Keep track of click count |} 
iF this activates a new window THEN 


| See “Activate a window’ chart T 


window.DowninContent 


| See “Mouse press ina view” chart M} 


acfivateEv 
| See “Activate a window” chart 


updatetvt ©) 
[S22 “Update event chart i] 


eyDown, auioKey 


IF thecmaKey THEN 
commandToPertorm := CommandKey O 
$ commandtioPertorm := glarget.DokeyCommand (7Y 


Final 
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Performing a command (Figure 7-5) 

l PerformCommand is called from the main event loop. Itis passed a command object 
returned by ObeyEvent, which obtains it from one of a number of methods such as 
DoMenuCommand and DoMouseCommand. 

1) Some commands do not do everything that needs to be done until the command can no 
longer be undone. CommitLastCommand calls gLastCommand.Commit, which gives the 
old command a chance to do anything it needs to do. 


2) SetUndoText changes the text in the Undo command to something appropriate. 
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Figure 7-5 
Performing a command 


gApplication.PerformCommand{command) 


— gApplication.CommitLastCommand ~~ 
J ef gLastCommand to command 
Set command. flarget to gTarget 
command.Dolt “> 


IF command.fCanuUndo THEN 


| Set cn to command.fCmdNumber || 


| ELSE set cn to cNoCommand |} 
mn GP Plication.SetUndoText(kShawUndo. cn) 
[FitausesChange eN up cnange count |] 
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' Choose a menu command (Figure 7-6) 


Figure 7-6 is the general chart for menu commands. It shows the first steps followed by 
MacApp when the user chooses a menu command. For commands handled by MacApp, 
the succeeding steps are shown in the appropriate chart. 


1) MainEventLoop runs until the user quits the application. See the “Main event loop” 
section for more information. l 


2) The gApplication.SetupTheMenus takes care of menu items that need to be enabled or 
checked and menu titles that need to be disabled. (The global variable gApplication holds a 
reference to the application object.) . 
3) You must provide a method called DoSetupMenus for each of your objects that needs to 
enable or check menu items. In general, each object that has a DoMenuCommand method 
(described in (5) below) also has a DoSetupMenus method. For every case in the 
DoMenuCommand case statement, there is an Enable or EnableCheck call in 
DoSetupMenus. In your DoSetupMenus method, you should first call INHERITED 
DoSetupMenus so that all prior objects in the target chain get the chance to enable menu 
items. Next, your method calls Enable to enable menu items that are never checked and 
EnableCheck to enable menu items that may or may not be checked. All items not explicitly 
enabled by some method are disabled. If you need to explicitly disable an item that may 
have been enabled by a predecessor in the target chain or by an overridden method, you can 
do that. See the “Changing menu. appearance and function” recipe in the Cookbook for 
details of DoSetupMenus. 


4) MenuSelect returns the number of the menu item that the user chose. 


CmdFromMenultem translates that number into the corresponding menu command constant 
(aCmdNumber). 


5) You must provide a method called DoMenuCommand for each of your objects that have 
menu commands. This method contains a case statement with branches for the menu 
commands handled by this object. (Several related menu items may be mapped to a single 
case branch.) Either create a command object and return it, or execute the command and 
Tetum a special value. If the command is not one handled by this method, the method calls 
INHERITED DoMenuCommand. See the “Creating Menu Commands” recipe in the 
Cookbook for details of DoMenuCommand. 


6) PerformCommand is the method that tells the command object to perform the command. 
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Figure 7-6 af 
Choose a menu command 


TApplication.MainEventLoop 


gApplication.GetEvent 3 


gApplication.ObeyEvent 
iF what = mouseDown AND whereMouseDown = inMenuBaor 
gApplicationSetupineMenus 
" glarget.DoSetupMenus (3) 


INHERITED DoSetupMenus 
tNextHandier.DoSetupMenus 


For unchecked menu items 
Enable 


Enabieltem 


For checked menu items 
EnableCheck 


Enableitern 
Checkitem i 


DrawMenubar 


KAO 


giarget.DoMenuCommand (s) 
CASE aCmdNumber OF E 


command you handle: create a command object 


OTHERWISE ; 
INHERITED DoMenucommand } | 


gAppicaron.rertomoommand 


TYourcommand.Dolt C6) 
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Update (Figure 7-7) . 


When a region on the screen needs to be redrawn, MacApp, the Toolbox, or your 
application invalidates the region. The Window Manager accumulates the invalid regions 
of a window into the update region for the window. An update event is generated in the 
event loop after other events are processed. Figure 7-7 shows the MacApp processing for 
an update event. The update event, like all events, is processed by , 
TApplication.ObeyEvent, which calls TWindow.UpdateEvent. 


1) BeginUpdate is a Window Manager routine that initiates the update process by setting 
the visRgn to the intersection of the visRgn and the update region. The purpose of this is 
to prevent the entire visRgn from being redrawn unnecessarily. 


2) The MacApp global procedure WindowFocus sets the origin and clipping region of the 
window (see Chapter 4, “Drawing”). It is called here to set up the grafPort for redrawing. 


3) This call to EraseRect erases the part of the window that needs to be redrawn by setting 
the visRgn of the portRect to the background pattern (white by default). 


4) You can implement AboutToDraw if you need to do some processing just before the 
view is drawn, such as swapping in disk-resident data needed to display the area in 
question. However your view must have set fInformBeforeDraw to TRUE. If 
fInformBeforeDraw is FALSE, AboutToDraw is never called. 


5) TYourView.Draw draws (at least) the contents of the rectangle that is passed to it. The 
rectangle is in view coordinates. Your method TYourView.DoHighlightSelection displays 
the selection in whatever form is appropriate for your application. See the “Drawing a 
view,” “Drawing an object in a view,” and “Optimizing drawing” recipies in the Cookbook 
for more information about Draw. 


6) EndUpdate indicates that the updating process is finished and restores the normal visRgn 
of the window. 
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Figure 7-7 © 
Update 


window. UpdateEvent 


| BeginUpdate jan 
f WindowFocu oS 
EraseRect ; 


A 


| Actually Trrame.DrawAll: Window doesn't overnde || 


iF fView.finformBeforeDraw=TRUE 
TYourView.AboutToDraw (4) : 
[window Focus] 


TFrame.Drawinterior 


Figure out what needs to be drawn 


frame DrawControis 


frame.DrawView 
if there is a view and it can draw : 


Find out how much fo draw 
Set the drawing rectangle 


fView. DispiayOnScreen 


_ TYourView.Draw 
TYourView DotighlightSelection (5) 


SNOWEXTICFESADAC 


view. DoDrawExtraFeedback 


For each contained frame 
frame.DrawAil 


lf appropriate. draw the borders 1 





EndUpdate (6) 
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Creating a window (Figure 7-8) 


1) DoMakeWindows is called as part of the process of creating a document. 
DoMakeWindows is just one of a number of calls in OpenNew and OpenOld. (See 
“Creating a new document” and “Open an old document from a menu” in this chapter.) 
You must override DoMake Windows and make calls similar to those shown here. 


2) You call NewSimple Window in the simplest, and most common, case. (See the 
“Creating a window” recipe in the Cookbook.) It creates a window with a single frame that 
shows a single view. You can call NewPaletteWindow instead. NewPaletteWindow 
creates a window containing a palette (or status) frame and a main frame. (See the 
“Creating a palette window” recipe in the Cookbook.) Also, you can write your own 
routine to create a window with other forms. See the “Creating a window with two or 
more views” recipe in the Cookbook for an example of how to do that. (The global 
variable gApplication holds a reference to the application object.) 


3) You may call the MacApp global procedures AdaptToScreen and SimpleStagger. 
AdaptToScreen adapts the size of the window to the size of the screen, in case the 
application is run on a Macintosh with a different screen size, such as a Macintosh XL. 
AdaptToScreen assumes the initial size of the window is adapted for the standard 
Macintosh screen. If there are other windows on the screen, SimpleStagger staggers this 
window so that it does not completely cover the other windows. If you call both 
AdaptToScreen and SimpleStagger, call AdaptToScreen first. 


4) If this window is being opened because an old document is being opened, the display 
state may be restored here. The display state should ideally be stored as part of the 
document. The display state includes everything that the user may have set while using the 
document: the scroll position, selections, and so on. 
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Figure 7-8 
Creating a window 


TYourDocument.DoMakeWindows 
 NewSimpieWindow 


| Create and initialize a frame || 


SimpleStagger 
if you want to restore the display state O 
do that here. 
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Creating a:new document (Figure 7-9) 


The same steps are followed whether the user opens the application icon from the Finder or 
chooses New from the File menu. (If the user opens the application icon, your 
application’s OpenNew method is called from TApplication.HandleFinderRequest. If the 
user Chose New from the application’s File menu, this sequence is called from 
TApplication. DoMenuCommand.) : 


The global variable gApplication is a reference to the application object. 


1) You always override the DoMakeDocument method to create a new object of your 
document type and to perform any necessary initialization of the document object. See the - 
“Creating a document” and “Initializing a document” recipes in the Cookbook for details of 
DoMakeDocument. 


2) Override TDocument.DolnitialState if you want anything to appear in the new document. 
TDocument.DolnitalState does nothing. 


3) You always override TDocument.DoMakeViews to make your document’s initial views. 
You don’t have to make all views you will ever use here; you can create views and install 
them at any time. See the “Creating a view” and “Initializing a view” recipes in the 
Cookbook for details of DoMakeViews. : 


4) You also always override TDocument.DoMakeWindows. See “Creating a window” in 
this chapter. Also, see the “Windows” section of the Cookbook for a number of different 
versions of DoMake Windows. 


5) TDocument.ShowWindows displays the windows that have their fOpenInitially field set - 
to TRUE. 


6) If you want to do something special when you open your windows, override 
TApplication.OpenWindow. TDocument.OpenWindows just calls aWindow.Open. 


7) The global variable gApplication is a reference to the application object. 
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. Figure 7-9 
Creating a new document 


gApplication. OpenNew 
TYourApplication.DoMakeDocument 


 avoutbacumentiveurbecement | 
| avourDocument.Nvourbecument | lYourDocument 


IE Fills the document with initial contents S 
| Livourscument Domakeviews O 


YourDocument.DoMakeWindows O 


| _ See “Creating a window” chart f 


| Displays the windows |} 


gAppiication.OpenWindow 
IF there is a document l 
~ window.fDocument.OpenWindow 


| _ You might override this |} 


ELSE 


|__ Adds the document to the Spelesior: sist lig 
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Open an old document from a menu (Figure 7-10) 


See the Choosing a menu command section for information on what happens before 
DoMenuCommand is called. When you open a document from the Finder, OpenOld is 
called from TApplication.HandleFinderRequest. 


1) To open a document in response to the Open command chosen from the File menu (and 
not from the Finder), MacApp calls the Toolbox procedure SFGetFile, which puts up the 
standard Toolbox dialog box to get the name of the document from the user. The document 
object is linked to the file returned by the Toolbox call. (The global variable gApplication is 
a reference to the application object.) 


2) You always override TApplication. DoMakeDocument with a method that creates a new 
document object of one of your application’s types. See the “Creating a document” and 
“Initializing a document” recipes in the Cookbook for details of DoMakeDocument. 


3) You also have to override TDocument.DoRead, so your document can read itself from 
the disk. See the “Saving and restoring data” and “Saving the display state” recipes from 
the Cookbook. 


4) DoMake Views and DoMakeWindows create your document’s views and windows, 
respectively. You always need to override these methods. ShowWindows displays the 
windows that have their fOpentInidially field set to TRUE. See the “Creating a view” and 
“Initializing a view” recipes in the Cookbook for details of DoMakeViews. Also, see the 
“Windows” section of the Cookbook for a number of different versions of 

DoMake Windows. 
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Figure 7-10 
Open from a menu 


gAppiication. DoMenuCommand 
aCmdNumber = cOpen 
gAppiication.ChooseDocument 





CGOCUMENT KEQArOMPFriIe 


TYourDocument. DoRead (3) 


lt i} Q 
| Adds the document to the application's list. 
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Save (Figure 7-11) 


This chart assumes that the user has made changes to the document since the last time it 
was saved. If not, the user cannot choose Save. 


1) If the document has already been saved at least once, proceed with the call to 


SaveOnFile. If not, proceed as for Save As (see the next section); that is, put up a dialog 
box asking the user to type a filename. 
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Figure 7-11 
Save 


document.DoMenuCommand 


aCmdNumber = cSave 


document.Save 
IF the document has not been saved before A 


| Same as Save As |} 


If there is enough space 
document.SaveViaiemp 


document.MakeNewCopy 


TYourDocument.DoWrite (2) 


document Freerile 
|| Free the temporary file resources |] 


if not enough space 


document. SavelnPiace 
TYourDocument.DoWrite 
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Save As (Figure 7-12) f 


The steps for Save As are the same whether or not the file has been previously saved. 
1) SFPutFile puts up a dialog box asking the user to type a filename. 


2) You have to provide an implementation of DoNeedDiskSpace that returns the amount of 
space needed to save the document. MacApp uses that to determine if there is enough room 
on the disk. If there isn’t enough space for the file, MacApp executes a sequence to see if 
there is a way to create enough space. You also need to provide an implementation of 
DoWrite to save the document’s data (usually using FS Write). See the “Saving and 
restoring data” recipe of the Cookbook for more about DoNeedDiskSpace and DoWnite. - 


Final page 7-25 


. Flow of Control MacApp Programmer’ s Guide 


Figure 7-12 
Save As 


gApplication.DoMenuCommand 


aCmdNumber = cSaveAs 


document.Save 





SFPutFile 
Seo “Save” chart © 
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Activate a window (Figure 7-13) 
When the user activates a window by clicking in it, the window shows its scroll bars and 
highlights its active selection. If you want the menus in the menu bar to change when the 
new window is activated, you can override TWindow.Activate. 


1) If the state is changing, generate an update event. 


2) Calling window.ActivateContents calls TFrame.ActivateContents to perform frame- 
related activation for the window. 


3) The same process is repeated for each frame. 
` 4) DoCheckPrinter makes sure the view knows how the printer is set up. 


5) The global variable gTarget is reset to be the local target of the window object; the 
purpose is to restore everything to its state when the window was deactivated. 
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Figure 7-13 
Activate a window 


window.Activate 
|| _ Called once for new front window, once forold JI 


IF state is changing Q 
window.Updatetvent 1 


window ActivateConten 


frame.FocusOnContainer 


FOR each visible scrolipar DO 
ShowControl, Validrect } 


FOR each contained frame DO (3) 


frame.ActivateContents ; 


rame.rocus § 


view. Activate 
TYourView.DoHighlightSelection 
IF beActive = TRUE 
view.DoCheckPrinter (4) 


Make SELF the front window 
Make gTarget the window's target 
Make gDocument the window's document 
Install the window's selection 


IF entering = FALSE 


This is actually a deactivate 
Make NIL the front window 
Make the window's target gTarget 
Set gTarget to gApplication 
Make gDocument NIL 
Set the mouse pointer to arrow 


iF fisResizabie=TRUE THEN 
window. DrawResizelcon 


DrawGrowicon 
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Mouse press in an application control (Figure 7-14) 


ff you have a control other than scroll bars in your frame, MacApp will tell you when to 
start tracking it. 


1) ObeyEvent is called from the main event loop when an event is received. See the “Main 
event loop” and “Obeying an event” sections for more information. (The global variable 
gApplication is a reference to the application object.) 


2) When the pointer is found to be in an application control, MacApp calls 
TYourFrame.DoTrackConrol. (The Inside Macintosh function FindControl determines 
which control, if any, was the object of the mouse press.) The 
TYourFrame.DoTrackControl method takes care of tracking the mouse and redrawing the 
screen as necessary until the user releases the mouse button. 


A command object is returned to DownInContent by DoTrackControl. The command 


object is then passed back to ObeyEvent. The command object is eventually passed to 
PerformCommand. See “Performing a command” for more information. 
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l Figure 7-14 
Mouse press in an application control 


gAppilication.ObeyEvent 
iF what = mouseDown AND whereMouseDown = inContent 
window.DowninContent 
window.FindFrame 


window.Focus 
GlobaiToLocal 


frame.FinadFrame - 


PtinRect 
FindControl 


FOR each containee DO E 
frame.FindFrame i 


frame. TrackAppConiroi 
TYourFrame.DotrackControl 


j Return an appropriate command object 
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Mouse press in the view (Figure 7-15) 


Figure 7-15 shows the MacApp processing when the user has pressed the mouse button in 
a frame, but not in any control. The purpose of this processing is to track the mouse as 
long as the user holds the button down. The resulting command object is treated as an 
ordinary command once the mouse button comes up. 


ObeyEvent is called from the main event loop chart. See the “Main event loop” and 
“Obeying an event” sections for more information. (The global variable gApplication is a 
reference to the application object.) 


-1) When the mouse button is pressed in the content region, MacApp finds which frame it is 
in and then, as it is not in any control, calls frame. TrackInContent. 


2) Your DoMouseCommand method creates a command object, called a mouse tracker, to 
track the mouse. See the “Tracking the mouse” recipe in the Cookbook for details of 
mouse trackers. 


3) The TrackOnce procedure is called with one of three parameters: trackPress, trackMove 
or tackRelease. In this case, it is called with trackPress, to tell your TrackMouse method 
that the mouse is down, and where it was pressed. 


2 


4) The FeedbackOnce procedure is called to allow your TrackFeedback method to display 
whatever feedback is appropriate at various times while the mouse is moving. When the 
first parameter to this procedure is TRUE, as it is assumed to be here, then the feedback is 
turned on. If you are satisfied with the default rubberband feedback (a flickering rectangle 
connecting the mouse down point with the current mouse position), you don’t have to 
override TrackFeedback. 


5) This loop is repeatedly executed until the user releases the mouse button. 


6) The mouse is not considered to have moved and no feedback is provided if the amourtt it 
has moved is less than the hysteresis value. Once it has moved at least that much, 
movedOnce is set to TRUE. 


7) If the mouse has moved more than the hysteresis amount, MacApp checks to see if the 
user has moved it outside of the frame. If so, the frame is supposed to scroll automatically, 
and AutoScroll is called to determine how much to scroll. The frame is not actually 
scrolled yet, however until FeedbackOnce is called with the first parameter FALSE to turn 
off the previous feedback. Then ScroilBy scrolls the frame: 


8) Whether or not automatic scrolling was necessary, TrackOnce is called here with the 
parameter trackMove, so that your TrackMouse method can do whatever it needs to do. 
Finally, FeedbackOnce is called again to turn on the feedback that reflects the new mouse 
position. 


9) At this point, the user has released the mouse button. FeedbackOnce is called with the 
first parameter FALSE, to tum off feedback. 


10) TrackOnce is called again with the parameter trackRelease, to tell your TrackMouse 
method that the user has released the mouse button. 
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11) The tracker object is returned to DownInContent, which passes it back to ObeyEvent. 
The command object is eventually passed to PerformCommand, which commits the last 
command and calls Dolt for the new command. If the tracker didn’t change the document, 
you should return gNoChanges the last time TrackMouse is called (when the trackPhase is 
trackRelease) so that PerformCommand will not be called. See “Performing a command” 
for more information. 
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TYourCommand.trackMouse | | 


“Qlastcommand.commit  } i 
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Chapter 8 
MacApp Debugging Facilities 


MacApp provides three debugging tools: 


e The Debug window. This is a window available when the MacApp code used with 
the application was compiled with debugging on. You can direct WriteLn statements 
to this window. In addition, this window allows you to use the Debug menu and the 
Interactive Debugger. 


> The Debug menu. This menu appears in the menu bar of any MacApp applications 
(that was compiled with debugging on) and that has the Debug menu in its resource 
file. Using this menu, you can control certain features of your application and cause 
certain information to be printed instantly or periodically in the Debug window. 


¢ The Interactive Debugger. This is a high-level debugger that runs in the Debug 
window. It takes control whenever there is an error and at the beginning and end of 
most methods and other routines in MacApp and, unless you specify otherwise, in 
your application. 


In order to use the MacApp debugging facilities, the version of MacApp and your 
application that you use must have been compiled with debugging on. See the “Building a 
MacApp program” section in Chapter 3 for how to tum off debugging. (The easiest way to 
tell whether or not a version has been compiled with debugging on is by its size: debugging 
code adds over 40K to the size of the MacApp object file. Note, though, that additional 
building block units such as UTEView, UPrinting, and UDialog also make the object file 
significantly larger, so you can only compare files with the same units.) 


None of the debugging facilities is available when MacApp is compiled without debugging 
code. (Optimized code never includes debugging code.) You can always, however, use 
the low-level MPW debugger, Macsbug with your MacApp application, even if it’s 
compiled with debugging off. Some information about using Macsbug with a MacApp 
application is included under “Using Macsbug with MacApp” in this chapter. See the 
Macintosh Programmer’ s Workshop Reference for complete information on Macsbug. 


You should always recompile MacApp and your application without debugging when you 
want to produce a production version of your application (the debugging facilities add over 
40K of code to the application). For information, see “What controls debugging code” in 
this chapter. 


Note: In order to have the full set of debugging facilities, you must link your 
application with UTrace and UWriteLnWindow. Those units are normally linked if 
you use the default build files. To have the Debug menu appear, you must have that 
menu in the resource file. It is included in the MacApp debugging resource file. 
Applications don’t need to have USES UTrace or UWriteLn Window themselves unless 
they call UTrace or UWniteLnWindow routines directly. (Note that you can call 
WniteLn without USES UWriteLnWindow.) 
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What controls debugging code 


Several factors control what you can do with the debugging facilties. They are described in 
this section. 


Compiler variables 

There are a number of conditional compilation variables defined in MacApp that are always 
TRUE when compiling with debugging on and always FALSE when compiling with 
debugging off. (You can also set their values individually from the compiler command 
line, although that is rarely done.) The variables are: 

qTrace 

qDebug 

qNames 


qRangeCheck 


To insert code that will only be compiled when one of these switches is TRUE, precede the 
code with: 


{$IFC variable} 
where variable is replaced by one of the compiler variables. Follow the code with 
{ SENDC} 


Everything between those switches will only be compiled when the variable is TRUE. 


The $D switches 


The $D compiler switches {$D++} and {$D+} cause the compiler to insert additional 
debugging information in the compiled code. 


When you use {$D++}, which is used most often, the compiler inserts an 8- or 16- 
character identifier after the return instruction of every method or other procedure. (16 
characters are used for a method; 8 are used for an ordinary routine.) In addition, the 
compiler generates a call to the Interactive Debugger at the entry and return of every routine 
and at every EXIT statement. When the Debugger is called in this way, you can stop the 
program with the Attention keys or the Interactive Debugger can stop the program because 
of a.breakpoint or because you had run the program with the Single Step command (see 
“Entering debugger mode”). 


When you use {$D+}, the compiler inserts the identifier, but does not generate any calls to 
the Interactive Debugger. 


In either case, the identifier allows the Interactive Debugger to display the name of the 
routine when it displays the stack. 
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Each switch affects every routine until the other switch or {$D-} is encountered. 


When you are debugging, you generally want every routine in your code to be covered by 
{$D++}. UObject includes the following switch: 


{$SIFC qTrace} {$D++} {SENDC} 

Because of that switch, very routine in a unit that names UObject in its USES 
clause(including all of MacApp) is automatically covered by {D++} unless you use {$D-} 
or {$D+}. (See the Macintosh Programmer's Workshop Pascal Reference for an 
explanation of these switches.) - 

If you want a particular routine to be excluded, embed it as follows: 

{$IFC qTRACE} {$D+} {SENDC} 


PROCEDURE Example; 


BEGIN 


END; 
{$IFC qTRACE} {$D++)} {SENDC} 
You can similarly embed a group of routines in the same switches. 
Note that the use of {$D-} alone is not recommended. Even with thoroughly debugged 
routines, it is better to have the routine’s name available. (In production code, the names 
are not included because the qNames compiler variable is set to FALSE.) 

Important: Assembled routines (such as those described in Inside Macintosh), or 


routines from units that do not use UObject (such as Paslib) are never governed by the 
$D switches. 


Including debugging code 

An application often includes code that is only for debugging. MacApp uses the compiler 
variable qDebug to control compilation of debugging code. To insert code that will be 
compiled only when debugging is desired, surround the code with 

{SIFC qDebug} 

and 


{SENDC} 
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All code within these markers is only compiled when qDebug is TRUE. 


Note: You can also write code so you can, when debugging, enable or disable features. 
See “The Experimenting Flag, X,” below. 


The Debug window 


The Debug window appears when you start up any application that is linked with a version 
of MacApp that is compiled with debugging on. It is a scrollable, movable, resizable 
window. It is initially inactive. -If you intend to use it often, you may want to position it 
and your other windows so that the Debug window is always visible. 


The Debug window can hold, by default, 52 lines of 80 characters. (This value is set in 
UMacApp.inc2.p, in a call to WWInit. You can change it, if you want.) 


Application mode and debugger mode 


When debugging code is included in a MacApp program, there are two distinct modes: 
application mode and debugger mode. In Application mode, the application runs 
normally (except for any special behavior you insert with debugging code), and the Debug 
window can be activated, resized, moved, and scrolled like any window. The application 
may use WriteLns to write information in the Debug window, and information may be 
written there in response to Debug menu commands or Interactive Debugger commands. 


Using WriteLn statements with the Debug window 


There is no special trick to using WriteLn statements and Write statements to print in the 
Debug window. MacApp uses UWriteLn Window, a unit provided with the MacApp, to 
set up the debugging window so that all WriteLn text goes to that window. (Note that, 
except for debugging, a WriteLn is never used to print text in a MacApp program. Instead, 
you use UTEView or the QuickDraw text calls.) 


You always enclose WriteLn statements with conditional compilation switches so they are 
not included in production code. See the section “Including debugging code”. 

Reading debugging information in application mode 

If you want to type in debugging information, you can use Read and ReadLn. As with 
WriteLn, you normally surround Read and ReadLn statements with conditional compilation 


switchesso they are not included in production code. See “What controls debugging code,” 
above. 


The Debug menu 


Any MacApp application that was compiled with debugging on and that has the appropriate 
information in its resource file has the Debug menu displayed in its menu bar. The Debug 
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menu lets you control certain features of your.application and print certain information in 
the Debug window. This section describes the commands in that menu. 


The rest of this section details the standard Debug menu commands. You can add 
additional commands by editing Debug.r and adding support for your commands. You 
may want to add your own commands in an additional Debug menu, rather than adding 
them to the MacApp Debug menu. See the sample programs for examples. 


Allow Trace of menu setups 

This is a toggle command. When it is checked and the Interactive Debugger is in trace 
mode (see “The Trace Command, T” under “Using the Interactive Debugger,” below) 
{$D++} program points are printed in the Debug window even during the menu setup 
cycle. 

Allow Trace during Idle 

This is a toggle command. When it is checked and the Interactive Debugger is in Trace 


mode (see “The Trace Command, T” under “Using the Interactive Debugger,” below) 
{$D++} program points are printed in the Debug window even during the idle cycle. 


“Do First Click” for this window 

This is a toggle command. When it is checked and the current window is deactivated and 
then activated, the mouse click that activates the window is also (assuming it is in the 
content area of the window) passed to gTarget. DoMouseCommand for action. When this 
is not checked, the first mouse click activates the window but is not passed to 
DoMouseCommand. 

Scale pictures in Clipboard to window 

This is a toggle command. When itis checked and the Clipboard window is displayed, any 
PICT data (pictures) in the Clipboard is scaled to the size of the window before being 
displayed. 

Show Debug window 


When you choose this command and the Debug window is closed, it is apros and made 
the active window. 


Show software version 


Choosing this command results in a call to the method gTarget.IdentifySoftware. That 
method normally prints the compilation data and time in the Debug window. 
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Show debugging info 


Choosing this command results in a call to gTarget.ShowDebuginfo. 
TApplication.ShowDebuginfo prints a variety of information about the application. You 
can override that method in your object types to print other information. 


Refresh front window 


Choosing this command invalidates the entire front window, resulting in an update of the 
contents (as well as the borders)-of the window. 


Show view borders 


This is a toggle command. When it is checked, lines are drawn around the edges of all 
your views. When it is not checked, the edges of your views are invisible, unless your 
descendant of TView draws its own edges. 


The Interactive Debugger 


The MacApp Interactive Debugger is a high-level command-line operated debugger 
available to MacApp applications compiled with debugging on. It operates in the Debug 
window. The Interactive Debugger is displayed when your application is in debugger 
mode. 


When you are in debugger mode, the Interactive Debugger prompts you with a f. In 
addition, the Interactive Debugger displays a square block cursor. The mouse is inactive 
and the mouse pointer is hidden. 


Entering debugger mode 


You can enter debugger mode by pressing and holding the “attention keys,” Shift-Option- 
Command. You then enter debugger mode at the next {$D++} program point. The 
Debugger prints Stopped at followed by the name of the routine containing the program 
point. 


In addition, debugger mode is automatically entered at the next ($D++} program point. | 
when 


e a breakpoint has been set at program points with this point’s identifier (see “The 
Breakpoint Command, B,” below) 


e the Interactive Debugger’s Single Step command (see “The Single Step Command, 
Spacebar,” below) is in effect 
Also, debugger mode is entered automatically when 
e the procedure ProgramBreak is called in the program 


e SysError (the operating system trap that usually displays a “bomb” alert) has been 
called. In this case, the program will not be able to continue, but you may be able to 
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use the Debugger to examine the circumstances of the error. (Some 68000 exceptions 
are included in this group.) 


For this last group, the Debugger can be entered at any point, and not just at {$D++} 
program points. 


What the Interactive Debugger prints when it starts 
When you enter debugger mode, the Interactive Debugger prints a line of text that identifies 
what routine was executing and some information about under what circumstances 
debugger mode was entered. These messages are explained below. 
BEGIN ROUTINENAME #SegmentNumber 


The routine ROUNTINENAME has just been entered. This could be due to the attention 
keys, a breakpoint, or the Single Step command. 


END ROUTINENAME #SegmentNumber 


The routine ROUTINENAME is about to return. This could be due to the attention keys, a 
breakpoint, or the Single Step command. l 


EXIT ROUTINENAME #SegmentNumber 


An EXIT statement in routine ROUTINENAME is about to execute. This could be due to 
the attention keys, a breakpoint, or the Single Step command. 


BREAK ROUTINENAME #SegmentNumber 

The MacApp global debugging procedure was called from routine ROUTINENAME. 
SYSER ROUTINENAME #SegmentNumber 

A 68000 exception (such as divide by zero) or a SysError error has occured. 

- In each case, if the routine is a method, ROUTINENAME has the format 


object-type-name .method-name 


Using the Debug window in debugger mode 


In debugger mode, the MacApp Interactive Debugger is in control, and the Debug window 
cannot be-activated, resized, moved, or scrolled normally. You can, though, use the 
following commands to control the window. 


© WF brings the Debug window in front of any other windows. 
° WB moves the Debug window behind any other windows. 


e WR allows you to resize the Debug window with the mouse. (You won’t be able to — 
use the mouse for anything else, though.) 


e The Backspace key scrolls the window up. 
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e The Return key scrolls the window down. 


There is no way to scroll horizontally in debugger mode. 


Interactive Debugger commands 


You can enter Interactive Debugger commands only when in debugger mode and when the 
2 prompt is displayed. Each command is a single character, generally the first letter of the 
command name. 


Some of the commands require parameters. In those cases, a message and a ? prompt is 
printed after the command is entered. In entering parameters in response to the ? prompt, 
terminate your input with Return. 


When the 2 prompt is displayed, an incorrect or inappropriate response is the same as the 
Help command. When the ? prompt is displayed, an inappropriate or incorrect response is 
ignored. 


The rest of this section describes the action of each command. The character you type for 
each command is given after its command name. 


The Help command 


The Help command displays a list of the Interactive Debugger commands. This list is 
printed whenever you type a character that is not a command. 


The Status command, ? 
The Status command, ?, prints the list of Debugger commands and also includes some 
Status information. The status information includes: 

e The value of A5 and thePort 

e Whether or not Trace mode is on (see “The Trace Command, T,” below) 

¢ Whether or not a breakpoint is set and, if so, where 

e The identifier and segment for the current {$D++} program point 


The Recent History command, R 


The Interactive Debugger logs the 63 most recent {$D++} program points encountered, 
whether or not the program stopped at them. 


The Recent History command lists all the saved {$D++} program points using a three- 
column format. The current {$D++} program point is at the bottom of the left column, the 
preceding point is above that, and so on. The oldest recorded $D++ program point is at the 
top of the rightmost column. , 


Important: This command may not work properly (that is, you may get an incorrect 
name) if automatic segment unloading is on (the default). Segments are generally 
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unloaded in the main event loop, so, the results of R are generally accurate if you have 
not entered that loop. You can turn off automatic segment unloading by giving the 
Toggle Flags command (F) followed by a U. 


The Parameters command, P 


The Parameters command displays the parameters of a procedure frame. Its output is in. 
hexadecimal. 


When you give this command, you are prompted for a stack frame number. (See “The 
Heap and Stack Command, S,” below.) You give the stack frame number as a decimal 
number, and press Return. (Pressing Return alone is equivalent to typing 0.) Level 0 is 
the routine where the program stopped. 


The Locals command, L 


The Locals command displays the local variables of a procedure frame. Its output is in 
hexadecimal. 


When you give this command, you are prompted for a stack frame number. (See “The 
Heap and Stack Command, S,” below.) You give the stack frame number as a decimal 
number and press Return. (Pressing Retum alone is equivalent to typing 0.) Level 0 is the 
routine where the program stopped. 


The Fields command, F 


The Fields command displays the fields of an object, in hexadecimal, and shows the 
object’s type and all ancestor types (except TObject, as explained below). 


When you give this command, you are prompted for the object you want to know about. 

You can give an object identifier, a handle in hexadecimal, or you can give a stack frame 

number in decimal, and then type Return. The stack frame number is interpreted as 

referring to SELF for the method in that frame. Ifthe routine in that stack frame is nota 

oo you are told there is no object at that level. (See “The Heap and Stack Command, 
,” below.) 


For certain objects that are referred to by global variables, you can give the global variable 
identifier. Those global variables are 


gTarget 
gLastCommand 
gDocument 
gApplication 
gDocList 
gFreeWindowList 
gClipview 
gClipUndoView 
gPrintHandler 


In the output of the Fields command, the fields of the object are divided into groups 
determined by the object type that declared the field. That is, inherited fields are listed 
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separately from fields declared for the object’s type. The name of each type is printed 
before the field. Here is an example: 


TEVTHAND 

10456: 00015643 0001 

TDOCUMEN 

1045C: 0645 8987 1087 9876 7575 9876 7563 7565 
1046C: 98767565 0645 8987 1087 9876 

TYOURDOC l 

10478: 7865 4387 FEA6 BCA4 


In this example, the object occupies locations 10456-1047F. Its type is 
TYourDocument = OBJECT (TDocument) 


The field declarations define four words (eight bytes or 16 nibbles) of data, which here 
occupy locations 10478-1047F. The immediate ancestor, TDocument, declares fields 
accounting for 14 words of data, shown here in locations 1045C-10466. The next 
ancestor, TEvtHandler, declares fields accounting for three words of storage from 10456- 
1045B. The ultimate ancestor, TObject, declares no fields and is always omitted from the 
Fields command output. 


The Display Memory command, D 


The Display Memory command displays the contents of any part of memory. 


It prompts for a hexadecimal address and then displays 16 bytes beginning at the specified 
address. The memory contents are displayed in both hexadecimal and ASCII. 


If you want to see the next 16 bytes, type the Display More command (M) at the next 2 
prompt. 


The Display More command, M 


This command can be given only immediately after the Display Memory Command or the 
Stack Crawl Command. It displays the next 16 bytes of memory or the next group of ` 
stacked procedure calls. See “The Display Memory Command, D,” above, and “The Stack 
Crawl Command, S,” below 


The Trace command, T 


The Trace Command tums Trace mode on and off. When Trace is on and you give the Go 
command (to re-start your application), the identifier for every {$D++} program point is 
printed. 


The program will slow greatly. Performance is especially slow if the Debug window is 
partially hidden by other windows. 


Once you restart the program, you are in application mode, and you can stop the program 


with the Attention keys (see “Entering Debugger Mode” under “The Interactive 
Debugger”). Also, any errors or breakpoints will stop the program. 
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Note that you may be able to use the Recent History command to print a trace of the last 63 
{$D++} program points even if Trace mode was not on. 


The Single Step command, Space bar 


The Single Step command, given by typing a space with the Space bar, restarts the 
program until the next {$D++} program point. The program point is identified. 


The Go command, G ; 


The Go command ends debugger mode and starts the application going again. The 
application continues until the user quits or the Debugger is given some reason to take 
control again. 


The Breakpoint command, B 


The Breakpoint command allows you to set a breakpoint at a {$D++} program point. 
When you next give the Go command, the program continues until the breakpoint is 
encountered. 


Only one breakpoint can be set at a time. Setting a new breakpoint cancels the old one. 


When you give the Breakpoint command, you are prompted for a routine name. Only the 
first eight characters are significant in a routine name. If you also give an object type, only 
the first eight characters of that are significant. (If the first eight characters of the name are 
not unique, a breakpoint is set for all appropriate routines.) Case is insignificant. 


If you want to set the breakpoint at a method you have two choices: 


e Give the name of the object type for the method. This will have the form object-type- 
name.method-name - 


The object-type-name must be the object type that implemented the method. (Note 
that you cannot give an object-reference variable identifier.) The break will occur 
only when that particular method is invoked. (That method is invoked either from an 
object of the type named or from an object of a descendant type, if the method named 
is not overriden by that particular descendant type or any intervening descendant 
types.) f 


ə Give the method name without a qualifying object type. The break will then occur on 
any method (or ordinary routine) with that name, regardless of what object type 
implemented it. 


The name you give is not checked to verify that it actually exists. 
You can set a breakpoint at any routine, regardless of whether it is currently in memory, 


but note that the break will not occur unless the named routine contains a {$D++} program 
point. . 
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The Clear Break command, C 


The Clear Break command clears any breakpoint set with the Breakpoint command. 


The Scroll Up command, Backspace 


Typing a Backspace when the 2 prompt is displayed scrolls the Debug window up one 
line. 


The Scroll Down command, Return 


Typing a Return when the 2 prompt is displayed scrolls the Debug window down one line. 


The Debug window commands, WF, WB, and WR 


These commands are used to manipulate the Debug window. 


° WF places the Debug window in front of any other windows and, if it is inactive, 
activates it. 


e WB places the Debug window behind other windows. 
e WR activates the mouse so you can resize the Debug window. The mouse cannot be 
used for anything else in debugger mode. 


Note: Applicaton windows cannot be updated in debugger mode, so if you use the WB 
command to move the Debug window behind other windows or resize the Debug 
window so that new parts of other windows are revealed, those windows will not be 
properly drawn until you reenter application mode and the windows are updated. 
The Output Redirect command, O 
The Output Redirect command redirects all Debugger window output into a file. 
When you enter this command, you are prompted for a filename. Enter any filename. (If 
the file already exists, it must be of type TEXT.) If you do not specify a volume or folder, 
the output will be written to it will be on the default volume in the default folder (that is, the 
foider containing the application). 


If you precede the filename with >>, the Debug window output is appended to the file. 
(Spaces between >> and the filename are ignored. 


If the file exists and you do not give >>, the contents of the file are erased. 
If the file does not exist, it is created. Its type is TEXT and its creator is MPS. 


To cancel this command, give the command again, and type a Return in response to the ? 
prompt. The file will be closed. 
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The Quiet Output command, Q 

The Quiet Output command is identical to the Redirect Output command, except trace 
information sent to the given file is not also printed in the Debug window. 

The Heap and Stack command, H 


The Heap and Stack command is actually the entry into a group of subcommands. After 
you give this command, you are prompted with a ? for a subcommand. 


_ All of the subcommands print information about the heap and the stack. 


The Help command, ? 


Typing a ? gives you a list of the subcommands. 


The Procedure Stack Usage Breakpoint command, + 
This command allows you to set a breakpoint on stack usage by a single routine. 


The stack usage of the routine is computed to be the difference between registers A7 and 
A6. This value will take into account the local variables declared in the procedure, other 
local variables used internally by compiler-generated code, and registers that are saved on 
the stack. It does not take into account any stack usage for passing parameters to routines, 
stack usage by Inside Macintosh routines (including QuickDraw), and stack usage for 
routines which do not contain a {$D++} program point. 


Setting breakpoints on total stack depth and individual procedure usage will help you to 
gauge how much stack space your application requires and to identify routines that have 
excessively high stack usage. (These may have several string parameters that are passed by 
value rather than by reference.) 


The Stack Usage Breakpoint command,. B 


This command allows you to set a breakpoint on total stack usage. Total stack usage is the 
difference between register A7 and the bottom of the heap. 


Setting breakpoints on total stack depth and individual procedure usage will help you to 
guage how much stack space your application requires and to identify routines that have 
excessively high stack usage. (These may have several string parameters that are passed by 
value rather than by-reference.) 


The Reset Stack Usage command, D 


This command allows you to reset the maximum stack usage value maintained by MacApp 
to determine if a stack usage breakpoint has been reached. Choosing D resets that value. 
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The Show Heap/Stack Information command, I 


This command displays information about the heap and the stack. 


The Print MaxMem command, M 


This command prints the value of MaxMem. See Inside Macintosh for information. 


The List Loaded Segments command, S 

This command lists all segments currently loaded. An asterisk (*) next to the segment 
number that indicates the segment is resident. 

The Toggle Flag Command, X 


The Toggle Flag command allows you to toggle a number of flags that govern the behavior 
of the Interactive Debugger. 


After you give this command, you are prompted for more information. Typing ? gives you 
a list of the flags. Typing the letter for one of the flags toggles the flag’s value. 


You can add new items to the list of flags by calling the MacApp global debugging 
procedure TRCFlag, found in UTrace. The interface is 


PROCEDURE TRCFlag(flagAddr: Ptr; flagChar: CHAR; flagDesc: 
TRCFDescription) ; 


You pass this procedure a pointer to a BOOLEAN, a character (used to toggle the flag), and 
a short description. Only twenty flags are allowed. If you do add flags, be careful not to 
assign the same letter to two different flags. 


The current flags are listed below.. 


The Report Memory Management Information flag, M 


When this flag is on and the number of master pointers changes, the old and new numbers 
are printed in the Debug window. When the Break flag is also on, the program is stopped, 
and you enter debugger mode. 


The Report Segments flag, S 
When this flag is on, a routine name is printed in the Debug window when a segment is 
loaded. Usually, this is the routine that caused the segment to be loaded (unless that 


routine has no {$D++} program point). When the Break flag is also on, the program is 
stopped, and you énter debugger mode. 
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The Break flag, B 

When this flag is on and the Report Segment flag, S, or the Report Memory Management 
flag, M, is also on, a break is generated whenever M or S causes something to be printed in 
the Debug window. 


The Automatic Segment Unloading flag, U 


This flag, when on, turns off automatic segment loading by the UnloadAliSegments 
routine. You might want to try this flag if you find that your program is mysteriously 


jumping off into an unexpected routine; you may have saved a pointer to a routine in a 
segment that MacApp unloaded. : 

The Ask About Allocation flag, A 

- When this flag is on and an object is created, the name of the routine and the type of object 
are printed in the Debug window. Debugger mode is entered and you are given a chance to 
replace the object reference with NIL. This is used to check handling of memory 
management. 

The Ask About Failures flag, F 

When this flag is on, every call to FailOSEr, FailResError, and FailMemError will give 
you a chance to enter an error code and make your application fail. This allows you to 
check that you recover properly from these kinds of errors. 

The Report Menu Commands flag, C 

When this flag is on and the user chooses a menu command, the command number is 
printed in the Debug window. 

The Report Events flag, E 

When this flag is on, details of any events (except Debug window events) are printed in the 
Debug window. 


The Intense Debugging flag, I 


The Intense Debugging flag toggles the value of the global variable gIntenseDebugging. 
By enclosing code in the statement 


-IF gIntenseDebugging THEN 


you can make code have effect only when gIntenseDebugging is TRUE. 
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The Debug Printing flag, P 


. When this flag is on and the orders user does any UPrinting operation, information about 
printing is printed in the Debug window. 


The Experimenting flag, X 


The Experimenting flag toggles the value of the global variable gExperimenting. By 
enclosing experimental code in the statement 


IF gExperimenting THEN 


you can make features work only when gExperimenting is TRUE. 


The Inspect Object Command, I 
This command allows you to inspect an object. 


When you give this command, you are prompted for the identifier of the object you want to 
inspect. You can identify it with a hexadecimal handle, an object name, or a decimal stack 
frame number. If you give a stack frame number, the request is interpreted as being for the 
object used to call the method at that level. (If itis not a method, you are told there is no 
object at that level.) 


For certain objects that are referred to by global variables, you can give the global variable 
identifier. Those global variables are 


gTarget 
gLastCommand 
gDocument 

' gApplication 
gPocList 
gFreeWindowList 
gClipView 
gClipUndoView 
gPrintHandler 


This command then calls the Inspect method for the given object. (When you implement 
Inspect, you should call INHERITED Inspect and then use WriteLn to display any 
information you want about your object type.) 


Using Macsbug with MacApp 


Although the MacApp debugging facilities are powerful, you may sometimes need to use 
Macsbug, the lower-level debugger shipped with the MPW shell. See the Macintosh 
Programmer's Workshop Reference for details on using Macsbug; this section has some 
additional information you may find useful for using Macsbug with MacApp programs. 


‘You can set breakpoints on methods as with any routine. If you want to set a breakpoint 
on all method calls, you need to know something about how method calls are implemented. 
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Method calls are implemented in different ways, depending on whether or not the code has 
been optimized using the optimization option of the MPW linker. When the code is not 
optimized (as is normaily the case until the code has been debugged and finalized), method 
calls are routed through the method dispatch routine, %_METHOD. If you want to set a 
breakpoint on all methods, calls, you can do so by setting a breakpoint on %_ METHOD. 
To find J. METHOD, link your program using the listing option of the Linker, giving -! 
and a filename. The listing gives a map showing all routines and their locations as an 
offset from register A5. Find % METHOD in that map and, in Macsbug, give the 


command 


dm ra5+offset Z 


where offset is the value shown for %_ METHOD in the map. The second and third word 
of the line produced by this command give the location of the method display routine. You 


can use this value to set a breakpoint on %_METHOD. 

When the code has been optimized, %_METHOD is not used, and it is not possible to 
make a general statement about how methods are called under those circumstances, 
although many wiil be called by a direct JSR. 


If you've stopped at a ($D++} program point, you can use a different method to invoke 


Macsbug in the routine containing the program point. 


1. While stopped at the {$D++} program point (which you can reach by setting a MacApp 


breakpoint or in any other way), invoke Macsbug from the MacApp Interactive Debugger. 
2. Give the Macsbug SC (stack crawl) command. A line of this form is displayed: 

sr @address FR fromAddress method.Object +offset 

where address and fromAdadress are two addresses, method is the routine containing the 
{$D++} program point, Object is the type that defined that method, and offser is the offset 
into the routine. 

3. Add 4 to the fromAddress and using that number type 

GT address 


where address is fromAddress plus 4. This sets a temporary breakpoint just beyond the 
{$D++} program point. 


4. Return to the MacApp Debugger and type G. You will enter MacsBug in the routine 
with the $D++ program point. 
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Chapter 9 
Globals 


The MacApp unit defines a number of global constants, variables, types, procedures, and 
functions. Some of those are internal or are not significant for applications. Other globals 
are documented in this chapter, and some globals that are only present when MacApp is 
compiled with debugging on are documented in Chapter 11, “Debugging Reference.” 


The globals documented here are described for your reference, but you will probably not 


use many of them directly. MacApp methods use the globals, but most globals are used by 
application code very rarely, if ever. 


Constants 

This section documents the constants defined as part of the MacApp package. Although the 
values of the constants are given here for your information, those values are subject to 
change. (In some cases, the values are particularly subjust to change and are not given 
here.) Normally, you should simply use the constant identifier and not concern yourself 
with its vale. 


The constants are categorized according to purpose. 


Copyright constant 
kCopyright = ‘Copyright 1984, 1985, 1986 Apple Computer Inc.'; 


Used to store the copyright notice for MacApp. 


Menu constants 


mBarDisplayed = 128; Identifies the menu bar resource that holds the menus that are 
initially displayed. 

mBarNotDisplayed = 129; Identifies the menu bar resource that holds menus that are 
not initially displayed. These menus include buzzword 
menus and menus that may be displayed later. 


The following constants identify the standard menus shared by all Macintosh applications. 


mApple = 1; Identifies the Apple menu, the leftmost menu in the menu 
bar. 
mFile = 2; Identifies the File menu. 


Final page 9-1 


Globals 


mEdit = 3; 


mLastMenu = 63; 


Command numbers 


MacApp Programmer’ s Guide 


Identifies the Edit menu. 


Identifies the last menu managed by MacApp’s 
DoSetupMenus methods. This commands in menus above 
this number are never unchecked or disabled by MacApp. 


These command numbers are passed to your methods, generally to 
gTarget.DoMenuCommand. Most are passed as a result of the user picking a menu 
command; command numbers are also used for other types of commands, such as typing 
or mouse commands. When the description says “MacApp catches this,” that means that 
the MacApp DoMenuCommand methods will handle those command numbers, often by 


calling application methods. 


cNoCommand 


cAboutApp 


File menu commands 


cNew = 10; 


cNewLast = 19; 


cSave = 30; 


eClose = 31; 


cSaveAs = 32; 


cSaveCopy = 33; 


cRevert = 34; 


cOpen = 20; 


cOpenLast = 29; 


Final 


Command number representing no command. MacApp 
catches this. 


Identifies the About application... command. MacApp 
catches this. 


Identifies the New command. MacApp catches this. (See 
also cNewLast.) 


Identifies the last New command. MacApp provides a range 
of New commands for applications that have different 
document types, and cNewLast identifies the end of the 
range. If you enable these commands, MacApp handles 
them. 


Identifies the Save command. MacApp catches this. 
Identifies the Close command. MacApp catches this. 
Identifies the Save As command. MacApp catches this. 


Identifies the Save a Copy In command. MacApp catches 
this. 


Identifies the Revert command. MacApp catches this. 


Identifies the Open command. MacApp catches this. See 
also cOpenLast. 


Identifies the last Open command. MacApp provides a range 
of Open commands for applications that have different 
document types, and cOpenLast identifies the end of the 
range. If you enable these commands, MacApp handles 
them. 
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cPageSetup = 176; Identifies the Page Setup command. MacApp catches this. 
cPrintOne = 177; Identifies the Print One command. MacApp catches this. 
ePrint = 178; Identifies the Print command. MacApp catches this. 
cPrintToFile = 179; Identifies the Print to File command. MacApp catches this. 
cPrFileBase = 176; Command numbers between these two bounds are sent to a 
cPrFileMax = 195; document’s fDocPrintHandler even if it is not in the target 

- chain. 
cPrViewBase = 201; Command numbers in this range are printing commands 
cPrViewMax = 250; applied to a displayed view that is in the Target chain. 
eQuit = 36; Identifies the Quit command. MacApp catches this. 


Edit menu commands 


With the following commands, cEditBase is subtracted from the command number to arrive 
at the appropriate number to pass to SystemEdit. This relationship is enforced in 
TApplication.[A pplication. 


cEditBase = 21; The number that is the start of standard editing commands. 

cUndo = 21; Identifies the Undo and Redo commands. (Those are a 
single menu command; which one is displayed depends on 
the phase of the current command.) MacApp catches this. 


cEditSep = 22; Identifies the line separating the Undo (or Redo) command 
from the Cut command in the menu. 


cCut = 23; Identifies the Cut command. UTEView catches this. 
Applications may also. - 


cCopy = 24; Identifies the Copy command. UTEView catches this. 
Applications may also. 


ePaste = 25; Identifies the Paste command. UTEView catches this. 
Applications may also. 


cClear = 26; Identifies the Clear command. UTEView catches this. 
Applications may also. 

cEditLast = cClear: Marks the last command in the Edit menu. ***Why have a 
command number for EditLast?*** 

cShowClipboard = 35; Identifies the Show/Hide Clipboard command. MacApp 


catches this. 
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Finder pseudocommands 


cFinderNew = 40; Given when the user creates a new document from the 
Finder, generally by opening the application icon. MacApp 
catches this. 


cFinderPrint = 41; Given when the user prints a document from the Finder. 
MacApp catches this, 


cFinderOpen = 42; _ Given when the user opens an existing document from the 
- Finder , generally by opening the document’s icon. MacApp l 
„catches this. 


Other command numbers 


cTyping = 120; For use in a typing command. Note that this isnot a menu 
s command, but is used in a buzzword menu to refer toa 
string for Undo or Redo. 


kNoItemNumber = -1; A UDialog constant representing “no item” in contexts where 
a dialog item number parameter is possible but none is 
present. Examples of its use are as the value of 
fltemNumber for a TRadioCluster object, which does not 
have a corresponding item in the actual dialog’s item list, and 
as the value of a dialog view’s fDfltButton if the dialog has 
no default button. . 


Alert constants 


These constants are resource ID’s that refer to items in the application’s resource file. The 
messages given are the ones these constants are intended for; if you include the standard 
MacApp resources, you will get these messages. Nothing is done to enforce that 
correspondence, however. 
The following standard should be observed: 

* Alerts 0 through 249 are reserved for UMacApp. 

* Alerts 250 through 299 are reserved for UPrinting. 

+ Alerts 300 through 349 are reserved for UDialog. 

e Alerts 350 through 399 are reserved for UTEView. 

* Alerts 400 through 449 are reserved for UAppleTalk. 

e Alerts 450 through 499 are reserved for future use. 

* Alerts 1000 and up are available for applications. 


See the “Failure Handling” recipe in the Cookbook for details on how these alerts are used. 
phGenError = 100 “Could not ^2, because “0. 41” 


phCmdErr = 101; “Could not complete the ‘^2’ command because 40. “1” 
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phUnknownErr = 102; “Could not complete your request because ^0. 41”. Used 
if no operation string is specified. : 

phSaveChanges = 110; “Save changes before closing?” 

phRevert = 111; “Revert to last version saved?” 

phBackToBlank = 112; “Revert to a blank document?” 

phPurgeOld = 113; ~ “OK to purge old version before saving new one?” 

phTooManyChars = 150; i “Too Many Characters”. Used to reject a paste command or 
keystrokes. 

phAboutApp = 201 “About appName...” 

phNoChanges = 207; “There haven't been any changes since last save” . 


phValueAdjusted = 300; “Value out of range; closest acceptable value substituted”. 
Displayed by default by TNumberText. Validate if it finds 
that a value supplied by the user is out of range. (From 


UDialog.) 
errReasonID = 128 Identifies the table of strings that describe error messages. 
errRecoveryID Identifies the table of strings giving recovery information 


corresponding to the error messages. 


errOperationsID Identifies the table of operation strings for use in building 
error messages. 


msgCmdErr = 0; Used in a Failure message parameter to indicate that the low 
word of the message is a command riumber. You use this by 
adding it to the command number (which must be greater 
than 0) to get the message value. 


msgAlert = $FFFFO000; Used ina Failure message parameter to indicate that the low 
word of the message is an alert resource number. You use 
this by adding it to the alert resource number (which must be 
greater than 0) to get the message value. 


msgLookup = $FFFE0000; Used ina Failure message parameter to indicate that the low 
word of the message is an index number for the table 
errOperationsID. You use this by adding it to the index 
number (which must be greater than 0) to get the message 
value. 


msgStrList = 200 * $10000; Identifies the standard list of operation strings used by 
MacApp. 


msginitFailed = msgStrList + 1; The index of the initialization failed message in 
msgStrList. 
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msgSaveFailed = msgStrList + 2; The index of the save failed message in 
f msgStrList. 


msgReadFailed = msgStrList + 3; The index of the read failed message in msgStrList. 


Buzz-String constants 


Buzz-strings are used in resource files to hold alternate wordings, usually for toggle 
commands. These constants are used for the buzz-strings defined in MacApp. The strings 
given are the ones these constants are intended for; if you copy those resources from the 
sample resource files provided, you will get these strings. Nothing is done to enforce that 
correspondence, however. 


The values here are indexes to the buzz-string resource, which is kIDBuzzStming in the 
standard resource file, also defined below. 


Important: The values here are subject to change. If you define buzz-string resources 
for your application, you should use a different resource. 


bzSaveAs = 1; “Save This Document As” 

bzSaveCopy = 2; “Save a Copy In” 

bzShowClip = 3; “Show Clipboard” 

bzHideClip = 4; “Hide Clipboard” 

bzUndo = 5; “Undo” 

bzRedo = 6; “Redo” 

bzCantDraw = 7; “Unable to draw contents of window” 

kIDBuzzString = 256; Resource ID of the standard list of buzz-strings stored as 


‘STR#’ resources 
Resource IDs 
These constants are used to identify resources in the application’s resqurce file. 
EN E SE = 0; Resource ID of the menu command number table. 


kIDCLlipWindow = 200; Resource ID of the window displaying the Clipboard. 


Highlighting constants 


hloff = 1; Indicates the selection is to have highlighting removed. 
hlDim = 2; Indicates the selection is to have dim highlighting. © 
hlon = 4; Indicates the selection is to have full highlighting. 
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The following constants can be used to test for combinations of fromH1l+toHL, when you 
do not care which is the old state.and which is the new state. 

hloffDim = hlOf£ + hlDim; 

hlDimoff = hloffDim; 

hlDimon = hlDimoOn; 

hloffOn = hloff + hlon; 


hionoftt = hloffon; 


Miscellaneous constants 


kMakingCopy = TRUE used in a number of calls to TDocument saving methods to 
indicate that a new copy of the file is being made. 

kDataOpen = TRUE; Used in call to TDocument.[Document to indicate that the 
data fork of the document file should be kept open all the 
time. 


kPrintInfoSize = 120; Size, in bytes, of the printInfo record. 


kRsrcOpen = TRUE; Used in call to TDocument.IDocument to indicate that the 
resource fork of the document file should be kept open all 
the time. 

kStdScrLimit = 300; Defines the default value of fScrollLimit, used in 


TFrame.[Frame. 


kStdScroll = 16; Defines the default value of fScrollUnit, used in 
TFrame.[Frame. 
kStdSzSBar = 16; Defines the width and height of a standard vertical and 


horizontal scroll bar. 


KStdSzMinus1SBar = kStdS$zSBar - 1; One pixel less than the size of a standard scroll 
. bar. 


kSwitchToTarget=FALSE; Used in a call to TDocument.SaveViaTemp . 


kUsesDataFork = TRUE; Used in a call to TDocument.IDocument to ndicate that the 
application uses the data fork of the document file. 


kUsesRsrcFork = TRUE; Used in a call to TDocument.[Document to indicate that the 
application uses the resource fork of the document file. 


kWatchDelay = 3*60; Defines the default number of clock ticks before cursor 
changes to a watch (approximately three seconds). 


kNotInFrame = inDesk; Returned by FindFrame if you pass it a point that is not in 
any frame. 
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kForDisplay = FALSE; Tells DoMakeViews whether the views are being created for 
the display as well as (possibly) for printing. 


kForPrinting = NOT kForDisplay; Used to tell DoMake Views whether views are 
being created only for printing (usually for Finder printing). 


kWantHScrollBar = TRUE; Used with the TFrame.IFrame method to display a 
horizontal scroll bar. 


kWantVScrollBar = TRUE; Used with the TFrame.[Frame method to display a vertical 


- scroll bar. 
- kHFrResize = TRUE; Used with the TFrame.IFrame method to allow horizontal 
resizing of the frame. 
“kKVFrResize = TRUE; Used with the TFrame.IFrame method to allow vertical 


resizing of the frame. 


kDialogWindow = TRUE; Passed toa number of window methods and routines to 
indicate that the window being defined is a dialog box. 


kRequestedSave = TRUE; Used with TDocumentSave so the user will be asked fora — 
file name (usually used with the Save As command). 


kAskForFilename = TRUE; Used with TDocument Save. 
kRenameDocument = TRUE; Used with TDocument.Save. 


kLeftPalette = h; Used with NewPalette Window to place the palette or status 
frame on the left of the window. 


kTopPalette = v; Used with NewPalette Window to place the palette or status 
frame at the top of the window. 


The following identifiers start with g because they are redeclared as global variables when 
qDebug is TRUE. They are described in Chapter 11. 


gExperimenting = FALSE; 
gDebugPrinting = FALSE; 


. GReportMenuChoices = FALSE; 


gReportEvt = FALSE; 
gintenseDebugging = FALSE; 
gUnloadAllSegs = TRUE; 
gMemMgtReport = FALSE; 


Types 


This section documents the data and object types defined as part of MacApp and the units 
shipped along with MacApp: TEView, UPrinting, and UDialog. These types are used for 
some of the global variables described in the following section, to declare parameters of 
many methods and global routines, and occasionally to declare variables in applications. 


The types are catagorized according to purpose. 
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Event types 


There are two types defined in MacApp for events. The first, pEventRecord, is a pointer to 
an EventRecord, the type defined for the Event Manager that is used to pass events to 
programs. The second type, Eventinfo, is an expanded event record which, as well as 
including a pointer to the original event record, has fields that make the information 
contained in the event record more accessible. 


PEventRecord = “EventRecord; A pointer to an event record. EventRecord is a data 
type defined as part of the Event Manager. See above. 


Eventinfo = RECORD The type for event information records created by MacApp. 
(See the explanation above.) 


thePEvent: PEventRecord; Pointer to the event used to derive the rest of the fields. 


theBtnState: BOOLEAN; The state of the mouse button. 
theCmdKey: BOOLEAN; The state of the Command key. 
theShiftKey: BOOLEAN; The state of the Shift key. 


theAlphaLock: BOOLEAN; The state of the Caps Lock key. ` 
theOptionKey: BOOLEAN; The state of the Option key. 


theAutoKey: BOOLEAN; TRUE if this was an auto-key event, issued as the result 
of a repeating key. 


theClickCount: INTEGER; Indicates the number of mouse clicks. 0 indicates the 
event was not a mouse down; value greater than 0 
indicates a number of clicks. 


END; 


Phases 


Several operations in MacApp have distinct phases: when the operation begins, as it 
continues, and when it is ending. The types described here are used to indicate the phases 
for the idle part of the event loop and for tracking the mouse. 


IdlePhase = (idleBegin, idleContinue, idle=nd); Defines the phase of the idle 
loop. IdleBegin is the phase when the idle loop first begins. 
IdleContinue is in effect until something happens to end the 
idle state. At that point, the idle phase becomes idleEnd. 


TrackPhase = (trackPress, trackMove, trackRelease) ; The phase of mouse 
l movement when the mouse button is down. TrackPress is 
the phase when the mouse button first goes down. 
TrackMove is when the button continues to be down. 
TrackRelease is the picture when the button comes up. 
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Command types 


CmdNumber = INTEGER; Holds MacApp command numbers. 


View coordinates 


"The size delimiter type tells how a view’s size is to be determined. The size is specified 
separately in each dimension. Its possible values are explained below its definition. 


SizeDeterminer = (sizeFrame, sizePage, sizeFillPages, sizeVariable, 
sizeFixed); f f 


sizeFrame View width or height the same as that of its frame. 
sizePage View to be the size of one page. 

sizeFillPages View to grow upward to fill an exact number of pages. 
sizeVariable View size fluctuates according to application-specific criteria. 


sizeFixed No special default handling of size issues. 


ImageSpace = (viewSpace, padSpace) ; 


PageAreas = RECORD Holds the parameters of a page. 
thePaper: Rect; The size of the physical page. 
theInk:Rect; The size of the printable page. 
. theMarginsRect; The margins of the page. The top and left are positive 


values; the bottom and right are negative values. 


theInterior: Rect; The rectangle into which the view subset will be projected. 


Highlighting types 


hiState = hloff..hlon; Defines a type for the possible highlighting states. 


Miscellaneous types 


PAppFile = “AppFile; This defines the pointer type AppFile, which. is defined in 
the Package Manager chapter of Inside Macintosh. This is 
used as a parameter to TApplication.KindOfDocument. 


SIPChoice = (sipNever, sipAlways, sipAskUser); SIP stands for Save In Place. 
This type is used for a value that determines what happens 
when there isn't room on the disk to save a document in a 
new file, rather than writing over the old version of the 
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document. (When the old version is overwritten, the file is 
“saved in place.”) 


Global Variables 


The global variables defined as part of MacApp and the other units can be considered fields 
of the application object. They hold information pertinent to the application as a whole and 
not specific to a particular document, view, or window. 


In general, you do not change the values of these variables directly, although you may 
check some values and MacApp methods you call may result in a change to a global 
variable. 


The variables you may change directly are so indicated; do not alter the values of any other 
global variables yourself. 


gAppDone : BOOLEAN; Indicates whether your application wants to terminate. 
Initialized to FALSE. MacApp sets this to TRUE when the 
user issues a Quit command. You may change this value if 
you want your application to terminate in other 
circumstances. 


gApplication: TApplication; The application object. 
gBreaksPenState: PenState; Holds the pen state normally used to draw page breaks. 


gChooserOK: BOOLEAN; Controls whether the user is allowed to change the printer 
with the Chooser desk accessory. Ordinarily set to TRUE in 
InitToolBox. Change it to FALSE if you don't want the 
user to be able to change the printer while your application is 
running. The right time to set this to FALSE, if you want it 
FALSE, is after calling InitToolBox and before calling 
InitPrinting (where, if it’s found to be FALSE, the low- 
memory location governing this option is poked). 


gClickCount: INTEGER; Holds the number of “saved up” mouse clicks. This is set in 
TApplication.ObeyEvent. When ObeyEvent receives a 
mouse-down event in the content area of a window, the 
value of gClickCount is set to that retumed by 
TApplication.CountClicks. If any other event (except a 
mouse-up event, which has no effect) is given to 
ObeyEvent, gClickCount is set to 0. | 


gClipFrame: TFrame; The frame in gClipWindow into which Clipboard views are 
installed. 


gClipOrphanage: TView; A view to represent the Clipboard when it can't otherwise be 
displayed. 


gClipwindow: TWindow; The window holding the Clipboard display. 
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gClipShowing: BOOLEAN; Indicates whether the Clipboard window is currently 
showing. 

gClipView: TView; The view currently installed in the Clipboard. 

gClipUndoView: Tview; The view previously installed in the Clipboard. 


gCmdTable: CmdTable; Maps command numbers to the menu and item IDs used by 
the Menu Manager. 


gCopyright: StringHandite; The copyright notice, 


gCouldPrint: BOOLEAN; Indicates whether printer code is accessible to the 
application. 


gCursorinfo: CursorīInfo; Information about the state of the cursor. 
gDialogView: TDialogView; The current dialog view. This is defined in UDialog. 
gDocument: TDocument; The current document. If there are multiple documents, this 
is the document belonging to the last window that was 
activated. 
gDecList: TList; The application’s list of documents. 
gDrawingPictScrap: BOOLEAN; Indicates whether or not a view’s Draw method is being 
- Called in order to create PICT data for the desk scrap. Your 
view’s Draw method can check this value and insert 
PictComments as appropriate if you want to have them in the 
picture stored in the desk scrap. 


gEventinfo:Eventinfo; An event information record for the most recent event passed 
to TApplication.ObeyEvent. 


gFileCount: INTEGER; The number of files to open or print from the Finder. This is 
set in Init2. 


gFinderPrinting: BOOLEAN; TRUE if the Finder started the application just for printing 
documents. 


gfreeWindowList: TList; The list of windows that do not have documents. 


gfrontWindow: TWindow; Contains NIL or the window object of the frontmost 
window. 


gHeadCohandler: TEvtHandler; The head of the linked list of global cohandlers. 

gHFSInstalled:BOOLEAN; Indicates whether or not the Hierarchical File System is 
installed. When this is TRUE and gROM128K is FALSE, 
HFS is in RAM. MacApp sets this value. 


gGotClipType: BOOLEAN; Indicates whether or not the Clipboard has data of a type that 
the current target can paste. 
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gidlePhase: IdlePhase: Stores the current idle phase. The value is idleBegin, 
idleContinue, or idleEnd. 

gLastCommand: TCommand; The command object for the last command done or undone 
by the user. May be NIL if there were no commands or if 
the last command cannot be undone. 


gLastDeskAcc: LONGINT; The time of the most recent possible invocation of a desk 


accessory. 

gLastEvent: EventRecord; The most recent event given to 
TApplication.MainEventLoop. 

gLastMsePt: Point; The coordinates of the mouse pointer in the last event passed 


to TApplication.CountClicks. 


gLastUpTime: LONGINT; The time of the last mouse-up event passed to 
TApplication.ObeyEvent. 


gMainFileType: OSType; The principal file type used by documents of the application, 
set in TApplication.[Application. By default, 
TApplication.SFGerParms returns a list that contains only 
this. 


gMenusAreSetup: BOOLEAN; Indicates whether or not the menus are properly set up. It is 
set FALSE after every event and set TRUE by 
SetupTheMenus, which is called at Idle Begin. 


gNoChanges: TCommand; A special TCommand object created by MacApp that you can 
return if the command does not change the document or no 
command results from an operation. You should carry out 
the command in the DoMenuCommand procedure. (Note 
that this is not a real object; you cannot refer to its fields or 
make method calls using gNoChanges.) 


gNullPrintHandler: TPrintHandler; A print handler to handle printing-related 
messages for views that don’t print. 


gOrthogonal: ARRAY[VHSelect] OF vHSelect; Used to convert VHSelect values. 
gOrthogonal[v] = h; gOrthogonal[{h] = v. 


gScreenSpotsPerInch: Point; The spots per inch on the screen. This is set to (72,72) 
for the standard Macintosh; other models may need different 
values. 

gSizeCmdTable: INTEGER; The size of gCmdTable. 


gStdHysteresis: Point; The standard hysteresis value used in 
_ TCommand.ICommand. 


gStdWMoveBounds: Rect; The standard boundsRect (of the screen) to pass to the 
DragWindow Toolbox routine. 
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gStdWSizeRect: Rect; The standard sizeRect to pass to the rome mnao Toolbox 
routine. 


gSysWindowActive: BOOLEAN; Indicates whether or not the front window is a system 
window, 


gTarget: TEvtHandler; The event handler that gets the first chance at DoCommand, 
DoSetupMenu, DoKeyCommand, and Doldle. You can set 
this although few applications do set it directly. (See the 
discussion of the target chain under “The Target Chain and 
~ the Cohandler Chain” in Chaper 2.) This is never set to 
NIL, 


gVarClipPicSize: BOOLEAN; Indicates whether or not pictures in the Clipboard should 
be treated as variable size, depending on the window size. If 
FALSE (the default), then pictures in the Clipboard are 
drawn actual size. 


gZeroRect: Rect; A rectangle all of whose coordinates are 0, obtained with 
SetRect(gZeroRect, 0, 0, 0, 0). 


Global routines 


Most of these routines can be called by your application. A few are called by many or most 
applications. Those that cannot be called are so indicated. 


Window-creation routines 


FUNCTION NewSimpleWindow(itsRsrcID: INTEGER; isDialogWindow: BOOLEAN; 
wantHScrollBar, wantVScrollBar: BOOLEAN; itsView: TView): TWindow; 


A utility for creating simple windows that contain one view and may 
or may not scroll, depending on the values of wantHScroliBar and 
wantV ScrollBar. Signals Failure if the window could not be created. 
This is often called by applications. Note that you usually do not 
call this if you call NewPaletteWindow. 


FUNCTION NewPaletteWindow(itsRsrcID: INTEGER; isDialogWindow: BOOLEAN; 
wantHScrollBar, wantVScrollBar: BOOLEAN; itsMainView: TView; 
itsPaletteView: TView; sizePalette: INTEGER; whichWay: VHSelect): 
TWindow; 


A utility for creating MacDraw-like windows with a nonscrolling 
palette along the left edge (if which Way is kLeftPallete), or a 
nonscrolling status area at the top of the window (if whichWay is 
kTopPalette),and a main view that may or may not scroll, depending 
on the values of wantHScrollBar (scrolls if wantHScollBar is 
kWantHScrollBar) and wantVScrollBar (scrolls if wantV ScrollBar. 
is kWantVScroliBar). (Precede those constants with NOT if you 
don't want scrolling.) Signals Failure if the window could not be 
created. 
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PROCEDURE SimpleStagger (aWindow: Twindow; dh, dv: INTEGER; VAR counter: 
INTEGER) ; 


Tells MacApp to make certain that the upper left corner of aWindow 
is staggered at least dh and dv pixels from the upper left corner of 
any other window, if possible. You should define a global variable 
for counter and initialize that to 0 in 
TYourApplication.TYourApplication. Pass in the same global 
variable each time you call this. If you have more than one window 
per document, you may want more than one counter variable so 
SimpleStagger can count different kinds of windows separately. 
This acts with a very simple algorithm and positions the window so 
the entire window is on the screen. The size of the window is not 
changed. If you are not satisfied with its results, you should 
examine its code and write your own version. This is intended for 
newly created windows, before they are displayed. 


PROCEDURE AdaptToScreen(aWindow: TWindow) ; 


Tells MacApp to adapt the size of aWindow (as defined in its 
resource definition) to a larger screen if the application is running on 
a computer with a screen size larger than the standard Macintosh. It 
does that by a simple algorithm, adding the difference in screen sizes 
to the defined size of the window. 


Command-related and menu-related routines 


The following routines all recognize normal command numbers and command numbers of 
the form ~(256 * menu + item) and (256 * menu). The former is used when there is no 
command number, the latter to enable or disable a whole menu (which is rarely done). 
PROCEDURE CmdToMenuItem(aCmd: CmdNumber; VAR menu, item: INTEGER); 
Given a command number, finds the menu ID and item number of 
the command. If aCmd is not in the command table, this returns 0 
as the menu number and ~aCmd as the item number. 
FUNCTION CmdFromMenultem(menu, item: INTEGER): CmdNumber; 
Given a menu ID and item number, return the command number of 
the command. If item <0 this returns —item. If the item is not in the 
command table, this returns (256 * menu + item). 
PROCEDURE CmdToName(aCmd: CmdNumber; VAR menuText: STR255); 
Given a command number, retums the text of the command. 


PROCEDURE Enable(aCmd: CmdNumber; canDo: BOOLEAN) ; 


Enables or disables a menu item, depending on the value of canDo. 
This is called by almost every application, because it must be called 
from DoSetUpMenus for every application-specific menu item that 
should be enabled. 


PROCEDURE EnableCheck(aCmd: CmdNumber; canDo: BOOLEAN; checkIt: BOOLEAN) ; 
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Enables or disables a menu item and places or removes a check mark 
next to the item. Many applications call this routine, always from 
DoSetUpMenus. 


PROCEDURE SetStyle (aCmd: CmdNumber; aStyle: Style); 


Sets the type style fora menu item. This is called from 
DoSetUpMenus, usually only for the type style items. 


FUNCTION LastCommandWas.(aCmdNumber: CmdNumber; aDocument: TDocument) ; 
BOOLEAN; 


Returns TRUE if the last command object has the command number ` 
and document fields set to the parameters passed to this routine. 


PROCEDURE GetResMenu(menuResID: INTEGER); 


Calls the Resource Manager routine GetResource(MENU', 
menuResID). You should use this routine when you are not sure if 
the menu is actually loaded in the menu bar. 


PROCEDURE SetCmdiIcon(aCmd: CmdNumber; menuIcon: Byte); 


. Alters the icon shown in the menu for the menu item with command 
number aCmd. You should call this routine to change the command 
icon rather than calling Menu Manage routines directly. 


PROCEDURE SetCmdName (aCmd: CmdNumber; menuText:Str255) ; 


Alters the text of the menu item with command number aCmd to 
menuText. You should call this routine to change the command text 
rather than calling Menu Manager routines directly. 


Segment-manipulation moutines 


Debugging note: You cannot set a MacApp breakpoint at any of these routines, because 
they must not call anything (such as %_BP) that may require a segment load. 


FUNCTION GetSegNumber(aProc: ProcPtr): INTEGER; 


Given a pointer to a procedure, returns the number of the segment 
containing the procedure. 


FUNCTION PreloadSegment (segNum: INTEGER): BOOLEAN; 


For programmers who want to lock a segment at the top of the heap 
without having to call a dummy procedure in that segment, returns 
TRUE if the segment could be loaded. 


PROCEDURE SetResidentSegment (segNum: INTEGER; makeResident: BOOLEAN) ; 


Makes a segment resident or no longer resident. Resident segments 
will not be unloaded by UnloadAllSegments. If a segment is made 
resident, it is also preloaded. MacApp automatically marks its 
resident segment as resident; you probably should call 
UnloadAllSegments before making a segment resident, to ensure 
that the newly resident segment is locked at the top of the heap. 
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PROCEDURE UnloadAllSegments; 


Unloads all segments execpt the blank segment and segments 
marked resident. 


FUNCTION SegmentLoaded(segHandle: Handle): BOOLEAN; 


Checks the given segment and returns TRUE if the segment is 
already loaded. 


Utility routines 


FUNCTION RectIsVisible(r: Rect): BOOLEAN; 


Returns TRUE if the given rect is visible in the current grafPort’s 
visRgn. If this is called during the update phase (as it normally is), 
that is, from one of your view.Draw methods or a method called by 
view.Draw, the visRgn is set to the region that is visible and needs 
to be updated. If printing, retums TRUE if the rectangle is on the 
current page. 


FUNCTION RectsNest (outer, inner: Rect): BOOLEAN; 


Returns TRUE if the rect given by inner nests within that given by 
outer. This returns TRUE even if the borders are the same. 


PROCEDURE Reduce (VAR numerator, denominator: INTEGER); 
Reduces a fraction to its lowest terms. 


PROCEDURE StdAlert (alertId: INTEGER); 


Displays a standard alert. It calls Alert with NIL filterproc and 
throws away the result. 


Failure-handling routines 


‘This section describes the global routines provided as part of MacApp’s failure-handling 
mechanism. These routines are intended to provide a generalized mechanism for failure 
recovery. See the “Failure Handling” recipe in the Cookbook for how to use these 
routines. 


PROCEDURE CatchFailures (VAR fi: Failinfo; PROCEDURE Handler(e: INTEGER; 
m: LONGINT) ); 


Sets up an exception handler. This pushes your handler onto a stack 

` of exception handlers. If MacApp has already pushed a handler 
onto the stack, yours is above it, so a call to Failure results in a call 
to your handler. Your handler generally calls Failure again to 
invoke the MacApp exception handler. 


PROCEDURE Failure(error: INTEGER; message: LONGINT) ; 


Signals a failure. This pops the most recently posted exception 
handler off the handler stack and calls it. FailNil, FailOSError, 
FailMemEnrror, and FailResError check for failures and then call this 
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routine. You generally call Failure either from your exception 
handler to invoke the MacApp exception handler (which would have 
been invoked first when the error occurred) or when you detect a 
failure condition not detected by FailNil, FailOSError, FailMemEn, 
or FailResError. You may call FailNewMessage in place of Failure. 
(That results in a call to Failure, but chooses between two possible 
messages first.) l 


PROCEDURE FailNewMessage (error: INTEGER; oldMessage, newMessage: 

LONGINT) ; 
This procedure calls Failure and passes the error and newMessage 
or oldMessage. FailNewMessage passes the oldMessage parameter 
to Failure unless it is 0, in which case newMessage is passed. This 
is used in an error handler so that the error handler can provide a 
message (newMessage) only if a message was not provided already. 
You would call this instead of calling Failure, if you wanted to set 
the message value to override a message value established by a 
lower-level handler. 


PROCEDURE FailNIL(p: UNIV Ptr); 
Called with a pointer or handler; this signals Failure(memFullErr, 0) 
if the pointer or handle is NIL. 

PROCEDURE FailOS&rr(error: INTEGER); 
Called with an OSError, signals Failure(error, 0) when error is not 
noErr. 

PROCEDURE FailMemError; 


Call this when you suspect there may have been a memory error, 
(gGenerally because you just attempted to allocate a new object.) ° 
Tests the value of MemError. If MemError <> noErr then this 
signals Failure(MemEnrr, 0). If you are using assembly language, 
then you should just test the return code from the Memory Manager 
in DO by calling FailOSErr. 


PROCEDURE FailResErr; 
Call this when you suspect there may have been a resource error. If 
ResError is not equal to noErr, this calls Failure(ResError, 0). 


PROCEDURE Success(VAR fi: FailInfo); 


Call this when you want to remove the most recently installed 
handler from the exception handler stack. Pops one element off the 
handler stack, but doesn’t call the handler. 


Miscellaneous routines 


PROCEDURE BusyDelay(newDelay: INTEGER; forceBusy: BOOLEAN); 


Changes the busy cursor delay. The newDelay value should be in 
sixtieths of a second; a value less than or equal to 0 means don’t 
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change the delay. If forceBusy is TRUE, then the watch is put up 
immedately, otherwise it doesn't go up until the required time has 
passed. 


PROCEDURE ResetBusyCursor; 


Changes the cursor back to an arrow and resets the time counted for 
the cursor delay before the pointer changes back to a watch. This is 
called automatically if you call GetNextEvent or EventAvail. 


PROCEDURE CanPaste(aClipType: ResType); 
Call this in your DoSetupMenus code to register an ability to paste a 


particular type of Clipboard data. 
PROCEDURE ClipFurtherTo(r: Rect; hDeltaOrg, vDeltaOrg: INTEGER); 
Set clipping to: 
r INTERSECT <current clipping> OFFSET-BY (hDeltaOrd, 
vDeltaOrg) 


PROCEDURE DeltaCtlValue(aControl: ControlHandle; delta: INTEGER); 


Adds delta to aControl’s control value, but does not call SerCr Value 
unless necessary. 


PROCEDURE EachHandler (aFirstHandler: TEvtHandler; PROCEDURE 
DoToEvtHandler(anEvtHandler: TEvtHandler; VAR stopNow: BOOLEAN) }; 


Performs DoToEwtHandler to aFirstHandler, then to its 
fNextHandler, and so on until the fNextHandler chain ends at NIL. 


PROCEDURE InitUDialog; 


Initializes UDialog. Call this exactly once, at initialization time if 
you use that unit. i 


PROCEDURE StdItemHandling(anItem: INTEGER; VAR done: BOOLEAN) ; 


Passed to TDialog View.TalkToUser calls for standard behavior 
within a modal dialog. This is declared in UDialog. 


PROCEDURE InitToolbox(callsToMoreMasters: INTEGER) ; 


Does essential Toolbox initialization. Every MacApp application 
should call this as the very first action in its main program. If you 
also use the printing unit UPrinting, call InitPrinting just after you 
call InitToolbox. The value callsToMore Masters multiplied by 32 is 
the number of master pointers initially allocated. New master 
pointers are automatically allocated if they are needed later, but that 
does not use memory as efficiently because that means allocating 
non-relocatable blocks). You should probably start with a value of 
three or four initially; when you are fine-tuning your application, 
you can use the MacApp Interactive Debugger Report Memory 
Management Information flag (see “The Toggle Flag Command, X” 
in Chapter 8) to find out how many master pointers you typically 
need. 
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FUNCTION PutDeskScrapData(aResType: ResType; aDataHandle: Handle): 


_ OSErx; 


Writes data to the desk scrap. Call this from your TView method 
WriteToDeskScrap. The return code from the Scrap Manager is 
returned as the function value. It will be noErr unless something 
went wrong. This procedure leaves aDataHandle unlocked. Rather 
than calling PutDeskScrapData, you can call the ToolBox routine 
PutScrap yourself. 8 


PROCEDURE FreeObject (obj: TObject); 


FUNCTION 


“FUNCTION 


FUNCTION 


FUNCTION 


Final 


If obj is not NIL calls the Free for that object. This is useful for 
freeing an object that might sometimes be NIL. 


LengthRect (r: Rect; vhs: VHSelect): INTEGER; 
Returns the length of the rectangle in direction vhs. 


LongerSide(r: Rect): VHSelect; 
Retums the direction of the longer side of the rectangle. 


Max(a, b: LONGINT): LONGINT; l 
Returns the larger of the two given integers. 


Min(a, b: LONGINT): LONGINT; 
Returns the smaller of the two given numbers. 
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Chapter 10 
Object and Method Reference 


This chapter describes the object types you may use that are defined in UMacApp, 
UObject, UList, UTEView, UDialog, and UPrinting. If you need information on objects 
and methods not described here, refer to the MacApp interface and implementation. 


This chapter assumes that you are familiar with each of the object types in a general way; it 
provides detailed information you’ll need for writing applications. If you need more 


general information about what each object type does and where it fits in, see Chapter 2. 


Chapter 5, “The Cookbook,” gives programming information you'll need to start on your 
application. You probably won’t need the detailed information about individual object 
types and methods given in this chapter until you are fine-tuning your appplication. The 
Cookbook recipes may also help you see where individual object types and methods fit into 
the scheme of a MacApp program, information that would be difficult to extract from the 
individual descriptions here. . 
Each object description in this chapter contains the following elements: 

e whether you customize the object type, instantiate it, or call its methods 

e notes about the object type 

e the chain of ancestors leading to the object type 

e field declarations and explanations 

e descriptions of the methods for each object type 

Important: Complete information about the implementation of each method is not given 


in this chapter. If you need further details about any method, refer to the MacApp 
source code. 
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TObject 


Customize: usually 
Instantiate: never 
Call methods: usually 


TObject is the ultimate ancestor for all objects in MacApp. 


TObject is documented here primarily for background information. It is an abstract object type that exists 
so that other object types can inherit characteristics from it, and thus share them. 


The only methods you might override are Free and Clone. 
- Ancestors: none. 


Fields 





none 
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Clone 

FUNCTION TObject.Clone: TObject; 

The return is an exact copy of the calling object 

value 

YAS o a e e e a aaaaaaaaaaaacaaaaaaaauauaaauaaaauauautusuaassssaulutl$utlulllMl— 
Purpose This method is intended to clone dependent objects referred to by the fields of an 


object as well as cloning the object itself. An object is dependent on another 
object when the second object has the only (or the only important) reference to 
the first object. Dependency is a relatively vague condition; when you override 
this method, you need to determine what objects are dependent on SELF. 


The default calls ShallowClone, and thus clones only the object itself 
version a 


Sometimes override 


Sometimes call 


ee e aaa aaaaaaaaaaaaaaaaacaaaaaasasaaasasasaiiauaasasassauasssssstultlMslttt$lMl 


Free 

PROCEDURE TObject.Pree; 

Purpose . This method is intended to free the calling object and any dependent objects 
referred to by its fields. An object is dependent on another object when the 
second object has the only Cor the only important) reference to the first object, 
Dependency is a relatively vague condition; when you override this method, you 
need to determine what objects are dependent on SELF. 


The default calls ShallowFree. 
version 
Often override Your version should free any dependent objects you have added for your 


customization and then call INHERITED Free so that any ancestor methods can 
free other dependent objects. The chain of INHERITED calls leads to 
TObject.Free, which calls TObject.ShallowFree, which frees SELF. 


Often call j 


L e e a aaa aaastal 


ShallowClone 
FUNCTION TObject.ShallowClone: TObject; 


The return is an exact copy of the calling object. 

value 
an 
Purpose This is the lowest-leve! method for copying an object. 

Called by TObject.Clone 

The default calls HandToHand, an Inside Macintosh routine, to copy the object data. 


version 
Never override 


Rarely call 


eR 


ShaliowFree 
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PROCEDURE TCbject.ShallowFree; 





Purpose This is the lowest-level method for freesing an object. 

Called by : TObject.Free 

The default frees the calling object and simply calls DisposHandle to free the calling object’s 
version data. 

Never override 

Rarely call 
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TEviHandier 


Customize: rarely 
instantiate: never 
Call methods: sometimes 


TEvtHandler is documented here primarily for background information. It is an abstract object type that 
exists so that other object types can inherit characteristics from it, and thus share them. 


The primary importance of TEvtHandler is that it allows the different objects that handle events to be 
stored in a single list. 


Ancestors: TObject 

Fields 

etdiePriority: INTEGER; Gives a priority value for the Doldle method of this object. If this is not greater 
` than zero, the default Idle method never calls this object's Doidle method. The 


default Idle method cails the Doldle methods of any handlers with fldlePriority 
values greater than zero. (The default value is 0.) 


fNextHandler: TEvtHandler; The next handler in the chain of event handlers, or NIL. 


Final page 10-5 


Object and Method Reference MacApp Programmer's Guide 





DoHandieEvent 

FUNCTION TEvtHandler.DoHandleEvent (nextEvent: PEventRecord; VAR commandToPerform: TCommana): 
BOOLEAN; 

nextEvent is a pointer to the new event 


commandToPerform is a command object that will perform the action indicated by the event or 
gNoChanges, if the action has already been done or the event resulted in no 
command. 


The return indicates whether or not the event has been handled. 

value 3 
a L 
Purpose is to handle an alien event. 


Called by TApplication.HandleAlienEvent. TApplication.HandleAlienEvent implements 
the cohandler chain. (See the “Target Chain and Cohandler Chain” in Chapter 2.) 

The default returns FALSE. 

version 

Always override this method ‘when you create a cohandler. A cohandler is an event handler that is 


not in the target chain and is not a view, window, document, application, print 
handler, or command object. You create cohandlers to handle alien events, 
which are generally asynchronous events like network events. Your 
implementation of DoHandleEvent should return TRUE if it handles the event and, 
otherwise, return FALSE. 


Never call 
i a a L 


Doidle 
PROCEDURE TEvtHandler.DoIdle(phase: IdlePhase); 


phase whether idle is just beginning, is continuing, or is ending: The declaration of 
IdlePhase is 


IdlePhase = (idleBegin, idleContinue, idleEnd); 


a re 


Purpose This method is called to do idle-time tasks. It is only called for event handlers 
when fidlePriority > 0 and the handler is inthe target chain or the cohandler 
chain. 

Called by TApplication. Idle 

The default does nothing 

version 


Sometimes override 


Never call 
Pe er 


DoKeyCommand 
FUNCTION TEvtHandier .DoKeyCommandi(ch: CHAR; aKeyCode: INTEGER: VAR info: Eventinfs): 
Toommand; 


aaaeaii aaaeeeaa o o aaa O 


ch - is a character typed at the keyboard. 
aKeyCode is the raw key code for the character ch. Note that this value may differ for different 
keyboards. i 
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info is the event information record that contains the key event. You can modify this 
parameter if you want 
. The return is a command object. 
value 
Purpose is to handle “key commands,” which are simply events resulting from keyboard 
i typing. : 
Caledby TApplication.ObeyEvent 
The default default implementation calls DoKeyCommand for the next handler in the list of. 
version handlers. If there is no “next handler,” the default method returns gNoChanges. 


Sometimes override If you override this method, generally for your descendant of TView or 
TDocument, you should return a command object that can respond appropriately 
to the character. See the description of TCommand in this chapter for more 
information. For simple editing, this method is implemented in the TEView unit. 
See the “Using TEView” recipe in the Cookbook chapter or the 
TTETypingCommand section of this chapter for more information.) 


Sometimes call You call this method, if you override it, by calling INHERITED DoKeyCommand. 
Otherwise, you never call it. 


DoMenuCommand 


FUNCTION TEvtHandler .DoMenuCommand (aCmdNumber: CmdNumber}: TCommand; 

aCmdNumber is the command number for the menu command chosen by the user. 

The return is a command object or, if there are no changes, gNoChanges. 

value 

Called by TApplication.MenuEvent when a menu command is chosen by the user. (A 
Command-key combination is usually equivalent to a menu command.) 

The default "calls fNextHandler. DoMenuCommanid if there is a next handler. If there is no 

version next handler; the default returns gNoChanges and, when compiled with debugging 


on, prints an error message. 


Often override this method to handle menu commands you have defined. In general, you return 
a command object to carry out the action of the command; if the command is 
simple and does not change the document, you can return gNoChanges. 


Often call this method if you override it, by calling INHERITED DoMenuCommand. 
Otherwise, you never call it. 


DoMultiClick 

SUNCTION TEvtkandler.DoMultiClick(lastDownPt, newDownPt: Point): BOOLEAN; 

lastDownPt the next-to-last point where the mouse button was pressed. 

newDownPt the most recent point where the mouse button was pressed. 

The return TRUE if lastDownPt and newDownPt are close enough to be a double-click. 
value 
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Purpose is to test whether a new mouse click should be counted as an additional click in 
gClickCount. It should return TRUE if newDownPt is close enough to lastDownPt to 
be considered the same point. 


Called by TApplication.CountClicks 

The default calls fNextHandler.DoCountClicks if there is a next handler. If there is no next 

version handler, it tests whether the difference between the two points is less than or equal 
; to five units, 

Rarely override If you want to change the standard for what is considered a new multiple click, you 


can override TApplication.DoMultiClick. The default version always calls 
fNextHandler. DoMultiClick unless fNextHandler is NIL, which is only true for the 
application object. 


Never call 
anan aa . 


DoSetupMenus 

PROCEDURE TEvtHandler.DoSetupMenus; 

Dananam eee e a e a 

Purpose This method is called before menus are displayed when the menus may have 

; changed since the last time it was called. It is also called after processing every 

event. It is responsible for adorning and enabling (or disabling) all menu 
commands handled by this event handler. 

Called by TApplication.SetupTheMenus and when an immediate descendant’s method calls 
INHERITED DoSetupMenus. 

The default calls DoSetupMenus for the next event handler in the list of event handlers. 

version (TEvtHandler is not responsible for any menu commands.) 


Sometimes override You must override this method if you define any menu commands. In general, 
you override this method for any object types where you override 
DoMenuCommand, and you handle the same menu commands in 
` DoMenuCommand and DoSetupMenus for a given object type. 


When you override this method, you must begin your method by calling 
INHERITED DoSetupMenus, so that MacApp can set up the menus first. Then, you 
use the global procedures Enable and EnableCheck to enable any menu 
commands that can currently be used or disable any that cannot be used. 
(EnableCheck, like Enable, can enable or disable menu commands. EnableCheck 
also can add or remove a check mark next to a menu item.) You can also adorn 
menus in other ways. See the “Changing menu appearance and function” recipe in 
the Cookbook for more detailed information. 


Sometimes call You always call this method when you override it. 
a ee 


lEvtHandler 

PROCEDURE TEvtHandler.lEvtuandler(itsNextHandler: TEvtHandler); 

itsNextHandler the next handler in the list of event handlers, or NIL 

Called by TApplication.[Application, TDocument.IDocument, TFrame.IFrame, 
TView.IView, and TPrintHandler.IPrintHandler to initialize an event-handler 
object. 
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The default sets the value of fidlePriority to zero and sets fNextHandler to itsNextHandler. 
version 


Never override 


PROCEDURE TEvtHandler. terminate? l l umm 


Call only if you declare immediate descendants of TEvtHandler. 

Terminate 

PROCEDURE TEvtHandler.Terminate; 

Purpose This method is intended to handle termination tasks for an event handler. 
The default i does nothing. 

version 


Sometimes override 


Never call The TApplication and TPrintHandler implementations of this method are called 
by MacApp. 


nS 
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TApplication 


Customize: always 
instantiate: never 
Cail methods: always 


The application object controls the overall application. In other words, it implements methods 
that apply to the application as a whole rather than to an individual document or window. 


You always customize TApplication to implement your application. 
Ancestors: TObject, TEvtHandler, TApplication 


Fields 


fIdlepriority: INTEGER; Gives a priority value for the Doldle method of this object. If not greater than 
zero, the default Idle method never calls this object’s Doldle method. The default 
Idle method calls the Doldle methods of any handlers with t fidlePriority values 
greater than zero. (The Doldle methods are called in the order of the handler list. 
If you want them called in a different order, override TApplication.Idle.) The 
default value is zero. This field is inherited from TEvtHandler. 


fNextHandler: TEvcHandler; The next handler in the chain of event handlers, or NIL. Inherited from 
TEvtHandler. 


Other fields are inherited but are never used. 


TApplication declares no additional fields. Many global variables are used like fields of the application 
object. 
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AddFreeWindow 

PROCEDURE TApplication.AddFreeWindow{aWindow: TWindow) ; 

aWindow is a window object.. 

Purpose is to add a window to the free window list. A free window is one that belongs to the 
application instead of a document (An example is the palette window in 
MacPaint.) 

Called by TWindow.IWindow. 

The default calls gFreeWindowList.AddLast(a Window) 

version 


Never override 


Rarely call 

ClaimClipboard 

PROCEDURE TApplication,ClaimClipboard(clipView: TView); 

clipView is the Clipboard view created to show the Clipboard contents. 
Called by the application to insert the given view in the Clipboard. 


Rarely override 


See the “Supporting the Clipboard” recipe in the Cookbook chapter 


Close 


PROCEDURE TDccument .cicse; 





Purpose is to close and free a document. This method must never be called for a document 
related to a view in the Clipboard. 

Called by TApplication.CloseDocument 

The default first calls the CloseWindow method for the document window (method is 

version implemented in TDocument), then calls gApplication.DeleteDocument to close 


the document. 
Sometimes override 


Sometimes call 


Someumes hr SS 


CloseDocument 

PROCEDURE TApplication.CloseDocument (docToClose: TDocument) ; 

docToClose is the document that should be closed. 

Purpose „is to close the document. It is called by MacApp when the user chooses the Close 


or Quit commands or, someumes, when the user closes a window. 


Called by TApplication.Close, TApplication.CloseWindow 
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The default if the document was changed since the last time it was saved, displays an alert 
version asking the user if the changes should be saved or the close canceled. If the 
response is to save the changes, this method calls docToClose.Save. 


Sometimes override 


Sometimes call 











CloseWindow 

PROCEDURE TApplication.CloseWindow(aWindow: TWindow) ; 

aWindow is the window being closed. 

Called by TApplication.CloseWmgrWindow and TDocument.Close to close a window. It is 


also called from TApplication.DoMenuCommand when the user chooses the Hide 
Clipboard command. 


The default if the window is the Clipboard window, the window is hidden. If the window has no 
version document (aWindow.fDocument = NIL), aWindow.Close is called. If 
aWindow.fWouldCloseDocument is TRUE, 
CloseDocument(a Window.fDocument) is called. Otherwise, 
aWindow.fDocument.CloseWindow(aWindow) is called. It signals Failure with err 
= 0 if the user cancels for some reason. 


Rarely override 
Sometimes call 





CloseWmegrWindow 

PROCEDURE TApplication.CloseWmgrWindow (aWmgrWindow: WindowPtr); 

aWmerWindow is the Window Manager pointer for a window that is being closed. 

Called by TApplication.DoMenuCommand (if the user choose the Close command) and 
from TApplication. DoMouseDown (if the mouse press was in the Close box). 

The default checks whether the window is a desk accessory window and, if it is, calls 

version CloseDeskAcc (an Inside Macintosh procedure) to close it. If not a desk accessory 


window, this method checks whether there is a window object for this window and, 
if there is, calls TApplication.CloseWindow. Otherwise, it calls HideWindow (an 
Inside Macintosh procedure). It signals failure with err = 0 if the user cancels for 
some reason. i 


Rarely override 


Never call 
SOMAS ee ee ee Se E 


CommandKey 

PROCEDURE TApplication.CommandKey (ch: CHAR; aKeyCode: INTEGER; VAR info: Eventinfo}); 
ch is the character of the key that was held down along with tie Command key. 
aKeyCode is the key code of the key that was held down along with the Command key. 
info is the event record. 
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Purpose is to handle events:in which a key is pressed along with the Command key, and that 
combination is not a Command-key equivalent of a menu command. 

Called by TApplication.ObeyEvent 

The default calls SetupTheMenus and MenuEvent if not auto-key or gRepeatcmd keys. 

version 

Often override this method to implement your own Command key commands or to implement 


key commands in your own way. Note: that you need do nothing with this method 
for command keys that correspond to menu commands and are given in the 
resource file. MacApp does not implement auto-key events (automatic repeating 
of keys held down) with Command-key combinations. If you want to implement 
auto-key Command-Key combinations, you must override this method. 


Never call 


i A 


CommitLastCommand 
PROCEDURE TApplication.CommitLastCommand; 


Called by TApplication.PerformCommand, TApplication.AboutToLoseControl, and 
TApplication.CloseDocument 

The default commits and frees the last command (gLastCommand) and changes the text for 

version the Undo command to show these there is no current undoable command. 


Rarely override 


Never call 

L aeea eaaa aeea eaea 
CountClicks 

FUNCTION TAcplication.CountClicks (aPDownEvent: PEventRecord); INTEGER; 

aPDownEvent is a pointer to the event record for a mouse down event. 

The return is the current number of multiple clicks. 

value 
i a naa aaa a IMaaaaaaaaaaaaaasaaauauaasasasasasasessststatstauatlMlM— 
Called by TApplication.ObeyEvent 

The default calls gTarget.DoMultiClick to see if the new mouse press should be considered an 
version additional multiclick. If so, it increments gClickCount. Otherwise, it resets 


gClickCount to 1. 
Rarely override 
Never call 


op I 


DeleteFreeWindow 


PROCEDURE TApplication.DeletefreeWindow(windowTobdelete: TALindow) ; 


windowToDelete is a member of the free window list. 
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Purpose is to remove a window from the free window list. A free window is one that belongs 
to the application instead of a document. (An example is the palette window in 
MacPaint.) 

Called by TWindow.Free. 

The default calls gFree WindowList. DeleteCwindowT oDelete). 

version 


Never override 
Rarely call 


DoMakeDocument 
FONCTION TApplication.DoMakeDocument (itsCmdNumber: CmdNumber)}: TDocument; 


itsCmdNumber indicates the type of document that should be created. In applications with 
different document types, the command number indicates which menu command 
the user picked or, if the user opened an existing document, a command number 
teturned by TApplication.KindOfDocument. 





The return is a document object. 
value 
Purpose this method creates a document for the application. It is called when the user starts 


up the application, opens 2 document with the New or Open command, and in 
other cases where the application needs to create a document. 


Called by TApplication.OpenNew, TApplication.OpenOld, TApplication.PrintDocument 
The default calls ProgramBreak to halt the program, because you 

version must override this method. 

Always override Your implementation of this method creates and initializes a document of your 


application’s type. If your application has multiple document types, your 
implementation of this method creates different document types depending on the 
value if itsCmdNumber. See the “Creating a Document” recipe in the Cookbook 
for details on this method. 











Sometimes call this method to create a document. (Most commonly, this method is called by 
MacApp.) 

DoMenuCommand 

FUNCTION TAppiication.DoMenuCommand(aCmdNumber: CmdNumber): TCommand; OVERRIDE; 

aCmdNumber is the command number of the menu command chosen by the user. 

The return is a command object that will carry out the command (and possibly undo and redo 

value the command), or gNoChanges. 

Purpose is to handle menu commands that apply to the application as a whole. 

Called by TApplication.MenuEvent when there is a menu command and gTarget is a 


reference to the application object or by some other DoMenuCommand method 
when no other object has handled the menu command. 


The default handles the MacApp defined standard menu commands Quit, New, Open, Close, 
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version Undo, Redo, ShowClipboard, About application, and the debug menu 
commands. 

Originally 

declared by TEvtHandler. 

Often override this method so that you can handle commands you define for your application 


object. In general, TYourApplication.DoMenuCommand handles the commands 
that apply to the application as a whole. When your implementation does not 
handle the command, you should end your override method by calling 
INHERITED DoMenuCommand, so that the MacApp method can handle its 
commands: 


Always call ~ this method if you override it. Otherwise, you never call it 





DoSetupMenus 

PROCEDURE TAppiication.DoSetupMenus; OVERRIDE; 

Purpose This method sets up the menu commands handled by the corresponding 
DoMenuCommand. 

Called before the menus are displayed when they may have changed since the last time 
DoSetupMenus was called. 

The default sets up the menu commands handled by TApplication.DoMenuCommand 

version 

Originally 

declared by TEvtHandler 

Often override You must override this method if you override TApplication.DoMenuCommand. 


Your override method must set up the menu commands handled by 
TYourApplication.DoMenuCommand. Begin your method by calling 
INHERITED DoMenuCommand so the MacApp methods can set up their menu 
commands first. See the “Changing menu appearance and function” recipe in the 
Cookbook for more details 


Always call this method if you override it Otherwise, you never call it 

EachFreeWindow 

PROCEDURE TApolication.£achFreeWindow (PROCEDURE DoToWindow(aWindow: TWindow)); 
DoToWindow is a procedure that will be passed each free window in tum. 

——_:._ $e 
Purpose is to apply DoToWindow to all windows in the “free window” list. A free window is 


one that belongs to the application instead of a document. (An example is the 
palette window in MacPaint) 


Called by your code and TApplication.ForAilWindowsDo. 
Never override 


Sometimes call this method if you have free windows. 





ForAllDocumentsDo 
PROCEDURE TApplication.ForAllDocumentsDo (PROCEDURE DoToDoc(aDocument: TDocument)); 
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DoToDoc is a procedure, usually local to the caller, that ForAllDocumentsDo calls 
tepeatedly, passing each of the documents in turn. 

Purpose This utility method can be called whenever an operation must be performed on all 
documents of an application. l 

The default automatically scans through the list of documents and calls DoToDoc once for 


version each document. 


Never override 


Sometimes call 





ForAllWindowsDo 

PROCEDURE TApplication.ForAllWindowsDo (PROCEDURE DoToWind(aWindow: TWindow}); 

DoToWind is a procedure, usually local to the caller, that ForAllWindowsDo calls repeatedly, 
passing each window in tum. 

Fe L LLL 

Purpose This utility method can be called whenever an operation must be performed on all 
windows of an application. 

The default calls PROCEDURE DoToWind once for each window of all documents of the 

version application and for any documentiess windows. 


Never override 
Sometimes call 











GetDataToPaste 

FUNCTION TApolication.GetDataToPaste(aDataHandle: Handle; VAR dataType: ResType): LONGINT; 
aDataHandle is a handle for Clipboard dau. 

dataType is a data type that is passed back to you. 

The return if non-zero indicates an error. 

value 

Purpose is to get data for pasting from the Clipboard. 

Called by your methods. 


Rarely override 


Always call this method if you implement the Paste command. You allocate an empty handle. 
and then pass it to this method. The dataType is not set here; it is one of the 
resource types you tell MacApp you can handle when you cail CanPaste (a MacApp 
global routine). The data may come from data cut or copied from your 
application or it may come from the desk scrap. 


See the “Paste” recipe in the Cookbook for more information. 
p 





GetEvent l 
PROCEDURE TApplication.GetEvent (eventMask: INTEGER; VAR anEvent: EventRecord): BOOLEAN; 
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eee 


eventMask is a mask indicating the kind of events wanted, 
anEvent is the event obtained. , 
The return indicates whether or not an event was obtained. 
value . 

s m 
Called by TApplication.PollEvent i 
The default calls the Inside Macintosh routine GetNextEvent. 
version R 


Sometimes override this method so that you can get events from another source. See Inside 
Macintosh for information on posting events. z 





Never call 

eee 

[Application 

PROCEDURE TApplication.iApplication(itsMainFileType: OSType) ; 

itsMainFileType is the unique four-letter type code for the main document files used bythe . 
application. 

— ee 

Called by TYourApplication 

The default initializes a number of global variables and otherwise initializes the application. 

version 

Never override Instead of overriding this method, you generally write a new method with a name 
of the form [YourApplication. 

Usually call this method from TYourApplication. 

idie 

PROCEDURE TApplication.Idle(phase: idlePhase} ; 

phase is the current part of the idle sequence: idleBegin, idleContinue, or idleEnd. 

Purpose This method is called when all events have been handled and there are no pending 
events. 

Called by TApplication.PollEvent 

The default ` begins by setting up the menus, if they need to be set up, and then gives each event 

version handler with IdlePriority > 0 a chance to run its Doldle method. 


Rarely override | 
Never call 


eee 


InstaliCohandler 


PROCEDURE TAppiication, InstallCohandler(aCohandler: TEvtHandler; addit: 30CLEAN); 






aCohandler is the handler you want to add to or remove from the cohandler list. 
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addit indicates whether aCohandler should be added to CTRUE) or deleted from (FALSE) 
the cohandler list. 

Purpose You call this method to add or remove cohandlers from the cohandler list. 

The default adds aCohandler to the cohandler list if addit is TRUE and deletes it if addlt is 

version FALSE. If aCohandler is deleted from the list, it is not freed. 

Never override l , 

Always call this method if you have cohandlers. 

KindOfDocument 


FUNCTION TApplication.KindOfDocument (itsCmdNumber: CmdNumber; itsPAppFile:- PAppriie): 
CmdNumber; 





itsCmdNumber is the command number from DoMenuCommand, or is cFinderNew, 
cFinderPrint, or cFinderOpen. 


itsPAppFile is a pointer to an AppFile record, or NIL. If not NIL, itsPAppFile^ fileType gives 
the four-character file type, which is usuaily all you need ta decide what type of 
document is needed. If NIL, this is a new document, so there is no existing 
document from which to get information. l 





The return is a command number to pass to DoMakeDocument. 

value i 

Purpose This method is used if the application has more than one kind of document type. It 
is called by MacApp to fix the command number whenever DoMakeDocument is 
called. ' 

Called by TApplication.OpenNew, TApplication.OpenOld, TApplication.PrintDocument 

The default returns itsCmdNumber. 

version 

Always override this method if your application has more than one kind of document. When the 


user opens an existing document, your implementation of this method uses 
itsPAppFile to determine what kind of document object should be created, The 
command number you return is normally the same as the command number for 
the New document menu command the user would choose to create a new 
document of that type. (in applications with multiple document types, you usually 
have different New menu commands for different document types.) 


Never call 





LaunchClipboard 
PROCEDURE TAppolication.LaunchClipboard; 


Called by TApplication. [Application 
The default starts up the Clipboard by creating a view and 2 window for it. 
version ; 


Rarely override 


Never call 


Final page 10-18 


MacApp Programmer's Guide Object and Method Reference 


eee 


MainEventLoop 


PROCEDURE TApplication.MainEvent Loop; i 
i 


Called by _ TApplication.Run : 
The default loops until the application begins to terminate. Events are dispatched from this 


version method and the Idle method is called from this method. 
Rarely override You might override it to’ change the progress of the event loop. If you do, examine 


the implementation of TApplication.MainEventLoop in UMacApp.incl.p. 
Never call 


oO reese 


MakeViewForAlienClipboard 


FUNCTION TApplication.MakeViewFo rAlienClipboard: TView; 


The return is a Clipboard view. 

value 

I er LU 
Purpose is to make a view to show the public scrap. In this case, the application has just 


Started or has returned from the Switcher or a desk accessory and the desk scrap 
contains data from another application or from another instance of this 


application. 

Called by TApplication.LaunchClipboard 

The default creates a view that can show PICT or TEXT data. 

version 

Usually override In your implementation, you check the desk scrap to see if it has data in one of the 
forms your application can handle (presumably because the data came Originally 
from this application or another application that creates compatible data). If data 
is there in that form, you create a view of one of your application's types to show 
the data and return that view. Otherwise, you call INHERITED 
MakeViewForAlienClipboard so that method can show the PICT or TEXT data. See 
the “The Clipboard” in the Cookbook for more information. 

Always call this method if you override it, in which case you call it by using INHERITED. 

ObeyEvent 


PROCEDURE TApplication.ObeyEvent (nextEvent: PEventRecord; VAR commandToPer‘orm: Toommancd) ; 








nextEvent is the event record obtained by GetEvent. 


commandToPerform is a command object created to do the action required by the event, or 
gNoChanges, 


a 
Called by TApplication.DispatchEvent 

The default determines what kind of event nextEvent is and dispatches it to the appropriate 
version target method. Ifthe event is not one of the events sent to the target (generally 


because it is an asynchonous event like a’ network event), it is sent to 
TApplication. HandleAlienEvent. 
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Never override 





PROCEDURE TApplication.OpenNew(itsCmdNumber: CmdNumber) ; 


itsCmdNumber is the command number that resulted in this call. 


eg SA hE SE 

Purpose is to create a new document, including the views and windows for the document. It 
is called whenever a new document is needed, either when the application starts up 
or when the user chooses the New command. 


Called by TApplication.DoMenuCommand, TApplication.HandleFinderRequest 


The default calls DoMakeDocument, DolnitialState, DoMakeViews, DoMake Windows, and 
version ShowWindows., 
Rarely override You may override this method if you don't want a new document to be 


automatically created when the application starts without the user opening an 
existing document. To do that, test the value of itsCmdNumber. If itsCmdNumber 
= cFinderNew, do not create the new document. See the UMacApp source for 
other details of the implementation to be certain you do everything necessary. 














Never call 

Opendld 

PROCEDURE TApplication.OpenOld(itsOpenCmd: CmdNumber; anAppFile: AppFile); 

itsOpenCmd is the command number that resulted in this call. 

anAppFile is an AppFile record. 

Purpose This method is called whenever an existing document is opened, either when the 
application starts up or after the user chooses the Open command. 

The default calls DoMakeDocument, DoinitialState, DoMakeViews, DoMakeWindows, and 

version ShowWindows. : 

Called by TApplication.DoMenuCommand, TApplication. HandleFinderRequest 

Rarely override 

Never call 

OpenWindow 

PROCEDURE TApplication.OpenWindow(aWindow; TWindow); 

aWindow is the window being opened. 

Called by TApplication. DoMenuCommand when the user chooses Show Clipboard (and the 
Clipboard isn’t already displayed). It is also called to open free windows. 

The default if the window is the Clipboard window, shows the window is shown (its state is 

version toggled and menu is updated). If’ the window has no document 


(aWindow.fDocument = NIL), aWindow.Open is called. Otherwise, 
aWindow.fDocument.OpenWindow(aWindow) is called. 


j 
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Rarely override 
Sometimes call Call this method instead of TDocument.OpenWindow 


PerformCommand 


PROCEDURE TApplication.PerformCommand (command: TCommand) ; 

command = isa command object to carry out the most recent command. 

Purpose is to carry Out a command that is not gNoChanges. 

Called by TApplication. DispatchEvent 

The default calls TApplicatign.CommitLastCommand, sets gLastCommand to the new 
version command, sets command.fTarget to gTarget, sets command.fCmdDone to 


TRUE, and calls command.Dolt. If the command is undoable, the default version 
puts the command’s name in the Undo command. If fChangedDocuiment <> NIL 
and fChangesDocument = TRUE, the default version increments the application's 
change count. 


Rarely override 
Never call 


a 

PrintDocument 

FONCTION TApplication.PrintDocument (anApoFile: AppFile) :. BOOLEAN; 

anAppFile is an AppFile record. 

The return tells whether or not the document was printed. 

value 

a IUO 

Called by TApplication.DispatchEvent to handle a Print command from the Finder, 

The default calls DoMakeDocument, ReadFromFile, and DoMakeViews, telling each that this 
is 

version being done just for printing, and then calls document Print for the new document 


Rarely override 


Never call 
a O 
Run 

PROCEDURE TApplication.Run: 

eg a‘ 

Called by your main program after you create and initialize your application object. 

The default does some initialization, calls TApplication.HandlerFinderRequest, and then 

version calls MainEventLoop. When MainEventLoop returns, Run calls 
AboutToLoseControl and CleanUpMacApp. 

Rarely override this method, although you might to do something different before calling 
MainEventLoop. If you do that, examine the implementation in UMacApp to see 
the details of the method. In general, though, it is better to create a different 
method, and call that before calling Run. 

Always call 
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SetUndoText 

PROCEDURE TApplication.SetUndoText (cmdDone: BOOLEAN; aCmdNumber: CmdNumber); 

cmdDone indicates whether this command is in do or redo phase CTRUE) or in undo phase 
(FALSE). 

aCmdNumber is the command number for the Undo menu command. 

Purpose is to set the text for the Undo menu command. 

Called by TApplication.CommitLastCommand, TApplication. DoMenuCommand, 
TApplication. PerformCommand 

The default changes the text to Redo if cmdDone = FALSE and back to Undo if emdDone = 

version TRUE. 

Rarely override 

Never call 

irh On E S E A 

ShowError 

PROCEDURE TApplication.ShowError(error: OSErr; message: LONGINT); 

error is an error number. 

message is a failure message. See the ‘Failure Handling” recipe of the Cookbook for more 
information. 

Purpose is to display an error message. 

Called by failure handlers 

The default calls the global procedure ErrorAlert. 

version 


Sometimes override this method if you want a different error message to be displayed. 


Sometimes call 











SwitcherEvent 

PROCEDURE TApplication.SwitcherEvent (switchingIn: BOOLEAN) ; 

switchingin indicates whether this application is being switched in (TRUE) or switched out 
(FALSE). 

Called by TApplication.ObeyEvent when it receives a Switcher event to handle the event. 

The default handles Switcher events. See UMacApp for details. 

version 


Sometimes override 


Never call 





SFGetParms 
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PROCEDURE TApplication.SFGetParms (itsCmdNumber: CmdNumber; VAR digID: INTEGER; VAR where: 
Point; VAR fileFilter, dlgHook, filterProc: ProcPtr; typeList: HTypeList); 


itsCmdNumber is the command number that resulted in this method call. 

digID is the resource ID for the dialog box that should be displayed. 

where is the position of the upper left corner of the dialog box in global coordinates. 

fileFilter is a pointer to a filter function that determines which files appear in the dialog box. 
If NIL, no filter function is executed. 

digHook is a pointer to a function that handles dialog items, or NIL. If NIL, no function is 
executed. ` 

filterProc is a pointer to a function that filters events, or NIL. If NIL, no standard filtering is 
done. 

typeList is a valid handle to a zero-length block. 

Purpose To get parameters that should be passed to SFPGetFile, which is an Inside 


Macintosh procedure that displays a dialog box listing files that can be opened by 
the application. 


Called by TApplication.CanOpenDocument, TApplication.ChooseDocument 


The default returns these values: 
version dlgID = getDlgID 


where = (100, 100) 
fileFilter = NIL 
GlgHook = NIL 
filterProc = NIL 


The typeList Parameter returns the main file type supported by the application. 


Sometimes override this method to return different parameter values. If the application supports all 
file types, you should make typeList empty. See Inside Macintosh for more 
information on the parameters of this method. 


Rarely call If you do call this method, you must set typeList to a valid handle and free the 
handle afterwards. 

a_a aaa aaaea 

SFPutParms 

PROCEDURE TApplication,SFPurParms (itsCmdNumber: CmdNumber; VAR dlgID: INTEGER; VAR where: 

Point; VAR prompt, defaultName: Str255; VAR dlgHook, filterProc: ProcPtr); 


itsCmdNumber is the command number that resulted in this method cail. 

dlgID is the dialog box that should be displayed. 

where is the position of the upper left corner of the dialog box. 

prompt is the prompt string that should be added to the dialog box. 

defaultName is the default name used in the dialog; it must be initialized to a valid suing when 
this method is called. 

digHook is a pointer to a function that handles dialog items; or NIL. If NIL, no function is 
executed. 

filterProc is 2 pointer to a function that filters events, or NIL. If NIL, no standard filtering is 
done. 
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Purpose to return all the parameters that should be passed to SFPutFile. 
The default returns: digID = putDigID 
version where = (100, 100) 
prompt = prompt from resource file 
algHock = NIL 
filterProc = NIL 


defaultName is left alone 


Sometimes override this method to change the default values. 





Rarely cail 

TrackCursor 

PROCEDURE TApplication.TrackCursor; 

Purpose is to track the mouse pointer while the mouse button is up. 

Called by TApplication. Idle 

The default checks the location of the mouse and calls SetCursor for the frame where the mouse 
version is located. 


Sometimes override this method to do something else while the mouse button is up. If you do that, you 
generally call INHERITED DoTrackCursor. 


Never call this method, except by calling INHERITED DoTrackCursor when you override it. 
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TDocument 


Customize: always 
Instantiate: never 
Cali metheds: rarely 


The document object controls the data of the document 


Almost every application must define at least one descendant of TDocument for its own document type. 
This is true except in the case of some “documentless” applications, in which the application icon is 
always opened. 


You generally add fields to your document type to store the views of the document 


If your application has more than one kind of document, you usually create more than one descendant of 
TDecument, one for each kind of document. For example, an integtrated application might have a 
TTextDocument, a TSpreadSheetDocument, and 2 TGraphicsDocument type. 


Most MacApp applications can have several document objects at a ume, which may all be of a single type 
or may be of different types. The document objects are stored in a TList object stored in gDocList. 


Each document object can have one document file. You can use the data and the resource fork sof the file 
or use either fork alone. Normally, the entire contents of the file is read into memory when the file is 
opened, but support is provided for disk-based documents. If the resource fork is used, the document's 
resource file is on top of the resource file list when DoRead and DoWrite are called. Otherwise, you need 
to call UseResFile to make sure the right resource file is on top. 


When a document is saved, MacApp normally saves the altered version of the document to a new file and 
then, when the save operation has been successfully completed, renames the new version of the file, 
erasing the old version. 


A number of the fields of TDocument determine whether the data and resource forks of the file are both 
opened and how the file is treated when it is saved: 


E fDataOpen and fRsrcOpen determine whether or not the data and resource forks of the file should be 
kept open at all times. Most applications set both to FALSE. An application can have either or both 
TRUE if the application uses disk-based documents. 


Note Keeping resource files open all the time is usually a bad idea 
because of the space required for multiple resource maps 
and slow searching of multiple files (especially with 64K ROMs). 
We recommend that keepskRsrcOpen always be FALSE. 


a fDataPerm and fRsrcPerm determine what Permission is used to open each fork of the file. Each of those 
can have the values 


® fsRdPerm for read-only permission 

@ fsWrPerm for write-only permission 

m fsRdWrPerm for read and write permission 
® fsRdWrShPerm for shared permission 


a fSavelnPlace determines what happens when there isn’t enough disk space to save 2 copy of the file 
instead of writing over the original. Its values can be 


& sipNever to indicate that the original file should never be overwritten 


æ sipAlways to indicate that the original file should always be overwritten when there is not enough 
space for a copy 


@ sipAskUser to indicate that the user should be asked whether or not the original file should be 
overwritten when there is not enough space for a copy 
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See the description of IDocument for information on how these fields are initialized. 


Programmers who want to implement work files such as MacWrite™ uses should open them in 
TYourDocument.IYourDocument and close them in TYourDocument.Free. TYourDocument.FreeData 
should reset the work file to the same state as TYourDocument TYourDocument.DolnitialState should set 
up the work file for an empty document (if necessary) and TYourDocument.DoRead should set up the work 
file for an existing document (if necessary). fSaveExists is a reliable indicator of whether a main document 
file exists or not (and, if fDataOpen or fRsrcOpen is TRUE, whether the corresponding refNum is valid). 


Ancesiors: TObject, TEvtHandler 


fields 7 


A a aaa 


fChangeCount: LONGINT; The number of changes since the last time the document was saved. 


fDataOpen: BOOLEAN; Whether or not the data fork of the document file should be kept open all the timc. i 
FALSE except for disk-based documents. ' 


fDataPerm: INTEGER; The permission used to open the data fork of the file: fsRdPerm, fsWrPerm, 
fsRdWrPerm, or fsRdWrShPerm. 


éDataRefNum: INTEGER; The reference number for the data fork of the document file, if that fork is now 
open. 


fDocPrintHandler: TPrintHandler; The object that enables and executes the Print, Print One, and Page 
Setup commands. 


fFileType: ostype; A four-character code giving the type of the document file. 
fPrintInfo: Handle; Either NIL or a handle to a 120-byte print information record 


fRsrcOpen: BOOLEAN; Whether or not the resource fork of the document file should be kept open all the 
time. 


fRsrePerm: INTEGER; The permission used to open the resource fork of the file: fsRdPerm, fsWrPerm, 
fsRdWrPerm, or fsRdWrShPerm. 


fSaveExists: BOOLEAN; Whether or not a disk file representing this document exists ; in other words, 
whether or not this document has ever been saved. 


£SaveinPlace: SIPChoice; The value that determines what happens when there isn’t room on the disk to 
save the document in a new file, rather than writing over the oid version of the 
document (when the old version is overwritten, the file is “saved in place”): 
sipNever, sipAlways, or sipAskUser. 


£SavePrintinfo: BOOLEAN; When this is set to TRUE and the document is saved, TDocument DoWrite 
writes the print information record of the fDocPrintHandler to the data fork of the 
document file. If this is TRUE, when the document is read, the print information 
record is read by TDocument.DoRead. 


‘SharePrintInfo: BOOLEAN; When this is set to TRUE, all print handlers associated with views belonging 
to this document will share the same print information record. (This value 
determines whether or not they will share that record.) 


fTitle: STRING(63}; The name of the document file. 

fUsesRsreFork: BOOLZAN; Whether or not the document uses the resource fork of the file. 
¢UsesDataFork: BOOLEAN; Whether or not the document uses the data fork of the file. 
£VolRefNum: INTEGER; The volume reference number of the document file. 


fWindowList: TList; The list of windows belonging to this document. 
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‘AboutToLoseControl 
PROCEDURE TApplication.AboutToLoseControl; 


Called by TApplication.SwitcherEvent, TApplication.ObeyEvent (when the user clicks in 2 
non-application window), and TApplication.Run (just before the end). 


The default commits the last command and writes the contents of the Clipboard to the desk 
version scrap (if necessary). . 


Sometimes override this method to do other tasks necessary before the application loses control. 


Never cali 
ene cer aee 
CloseWindow 

PROCEDURE TDocument .CloseWindow(aWindow: TWindow) ; 

aWindow is the window that should be closed. 

Purpose is tọ close a window belonging to a document. 

Called by TApplication.CloseWindow, TDocument.Close 

The default closes aWindow. If aWindow.fWouldCloseDoc is TRUE, SELF.CloseDocument is 
version also called. If the user cancelled the close operation, the method signals Failure 


with an error of zero. 
Sometimes override 
Sometimes call 


a 
DolnitialState 
PROCEDURE TDocument .DoInitialst ate; 


Called by MacApp methods when the user chooses the New command, when the user 
chooses the Revert command when there is no saved file, and when the user opens 
the application icon. It does: any additional initialization of the document that is 
not done when an existing document is opened. 


The default does nothing 

version 

Often override You should override this method when new documents need initialization not 
done when existing documents are opened. 

Never call 

a 

DoMakeWindows 


PROCEDURE TDocument. DoMakeWindows; 


Purpose is to create the window objects for a document. This method is called after a 
document is opened, initialized, and has its views created. This method should 
create the windows and frames to show the views. 


Called by TApplication.OpenNew, TApplication.OpenOld 


The default calls ProgramBreak to stop the application. 
version 
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Always override In your‘implementation, you usually use one or both of two MacApp global 
procedures to create your windows: NewSimpleWindow and NewPaleteWindow. 
See the “Creating a Window” recipe in the Cookbook for details on how to 
implement this method. 


Never call 


er 


DoMakeViews 
PROCEDURE TDocument .DoMakeViews(forSrinting: BOOLEAN); 


forPrinting tells you whether or not MacApp called this in response to the user requesting 
printing of a document from the Finder. If your application creates views that are 
not printed (such as palette views), you do not need to create them when 
forPrinting is TRUE. 


Purpose is to create the views for a document, both the views that interpret the document's 
data and those, like palettes, that are independent of the data: It is called after a 
document is created and initialized and before the windows are created. 


Called by TApplication.OpenNew, TApplication.OpenOld, TApplication.PrintDocument 


The default calls ProgramBreak to halt the program. 
version 
Always override Your implementation creates all views for the document and stores the views in a 


field of the document object. See the “Creating a View” recipe in the Cookbook for 
details on how to implement this method. - 


Never call 

a E a aaacasa 
DoMenuCommand 

FUNCTION TDocument .DoMenuCommand(aCmdNumber: CmdNumber): TCommand; OVERRIDE; 

aCmdNumber is the command number of the menu command chosen by the user. 

The return is a command object that will carry out the command (and possibly undo and redo 
value the command) or gNoChanges. 

Purpose is to handle menu commands defined for this particular object type. 

Originally TEvtHandler 

declared by 

The default handles the MacApp-defined standard menu commands Save As, Save a Copy In, 
version Save, and Revert. 

Often override You override this method when your application has its own menu commands that 


apply to the document as a whole. In that case, you end your method by calling 
INHERITED DoMenuCommand so that the MacApp method can handle its 
commands. 


Call this method when you override it. Otherwise, you never call it 


DoNeedDiskSpace 
PROCEDURE TDocument .DoNeedDiskSpace (VAR dataForkBytes, rsrcForkSytes: LONGINT); 
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_-_o eee 


dataForkBytes is set by this method to indicate the amount of disk space the document needs to 
save itself. 

rsrcForkBytes is set by this method to indicate the amount of disk space the document needs to 
save itself. 

-oO- ee eee 

Purpose is to return the amount of disk space needed to save the document. 

The default returns 0 for dataForkBytes, unless fSavePrintInfo is TRUE, in which case it returns 

version the size of the print information record. The default sets rsrcForkBytes to 0, unless 


fUsesRsrcFork is TRUE, in which case it sets to the standard fixed overhead value for 
the resource file. (See the “Resource Manager” chapter of Inside Macintosh for 
more information.) i 


Almost always override Documents that do not override DoNeedDiskSpace generally cannot save any 
data except the print information record. 


Your override method should accurately predict how much disk space will be 
needed to store the data and resources for the documents. (Most documents have 
no resources, so the resource fork value is usually 0.) When you calculate your 
values, you do not have to calculate how many blocks are actually needed, just the 
number of bytes. MacApp automatically accounts for an integral number of 
blocks. Also, you should add your needs to the initial values of these variables, as 
MacApp may have already set them to some value before calling this method. 


If there isn’t enough space in the target volume, MacApp tests whether deleting the 
old file would make enough room. If it would, what happens next depends on the 
value of fSaveInPlace. See the notes at the beginning of the TDocument section for 
more information. If deleting the file would not make enough space (or is 
precluded by the value of fSavelnPlace or the user's actions), MacApp issues a disk 
full error and the user is shown an alert to that effect. 


Never call 


DoRead 


PROCEDURE TDccument .DoRead (aRefNun: INTEGER: rsrcExists, forPrinting: BOOLEAN) ; 


aRefNum is a file system reference number for the document file. It is obtained from the 
Operating System by MacApp. If the document doesn’t use the data fork (that is, it 
uses only the file's resource fork), aRefNum is 0. 


rsrcExists indicates whether or not the resource fork of the file exists. If it is FALSE, and the 
document uses the resource fork, it means the resource fork could not be opened 
(presumably because it does not yet exist). 


forPrinting is TRUE if the document is being opened just to print it (for Prinung from the 
Finder). 

Purpose is to read an existing document file so its data can be used in the document object. 

The default reads the print information record if fSavePrintinfo is TRUE for this document 

version object. Otherwise, it does nothing. 


Almost always override Documents that do not override this method cannot save or restore anything 
except their print information record. 


Final Page 10-29 


Object and Method Reference MacApp Programmer’ s Guide 


DoSetupMenus 


If your document uses the resource fork and the resource fork exists, then MacApp 
will ensure that the topmost resource file is that of the document when this method 
is called. You may want to get the reference number of the resource file at the start 
of this method if you think that some other method might change the top resource 
file. 


Your implementation generally begins with a call to INHERITED DoRead so the 
print information record is read, if necessary. It then reads the data of the 
document, and stores it in fields or objects available to the document object. You 
should check the rsrcExists parameter before trying to read the resource fork. Atis ` 
possible that the user opened a document with no resource fork. MacApp does not 
consider this an error.) 


See the "Saving and Restoring Data” recipe in the Cookbook for details of 
implementing this method. 


this method if you override it. When you override this method, you usually call it 
(by calling INHERITED DoRead). Otherwise, you never call it. 


PROCEDURE TDocument.DoSetupMenus; OVERRIDE? 


Purpose 


Originally 
declared by 


The default 
version 


Often override 


Usually call 


DowWrite 


is to set up the menu commands handled by TDocument.DoMenuCommand. 
This method is called before any menu is displayed when the menus may have 
changed since the last time it was called or from the idle loop, again when the 
menus may have changed since the last time this was called. It is responsible for 
adoring and enabling or disabling all menu commands handled by the 
document. 


TEvtHandler 


begins by calling INHERITED DoSetupMenus. It then sets up the menu 
commands handled by TDocument.DoMenuCommand: Save As, Save Copy, 
Save, and Revert. 


- You override this method if you define any menu commands that apply to your 
document In general, you override this method whenever you override 
TDocument.DoMenuCommand. Your implementation must begin by calling 
INHERITED DoSetupMenus so that MacApp can set up the menus first. Then, you 
use the global procedures Enable and EnableCheck to enable any menu 
commands that can currently be used. (EnableCheck, like Enable, can enable or 
disable menu commands. EnableCheck also can add or remove a check mark next 
to a menu item.) You can also adorn menus in other ways. See the “Changing 
Menu Appearance and Function” recipe in the Cookbook for more detailed 
information. 


this method when you override it. Otherwise, you never call it 


PROCEDURE TDocument .DoWrite(aRefNum: INTEGER; makingCopy: BOOLEAN); 
EE i ae 


aRefNum 


Final 


is a file-system reference number for the document file. It is obtained from the 
Operating System by MacApp. 


page 10-30 


MacApp Programmer’ s Guide Object and Method Reference 


makingCopy indicates whether DoWrite is being called to save a copy. of the document 
(Generally used only for disk-based documents.) 

Purpose is to save a document's data to a disk file. 

The default saves the print information record to the disk file if fSavePrintInfo is TRUE. 

version Otherwise, it does nothing. 


Almost always override Documents that do not override this method cannot save or restore anything 
except their print information record. 


Your implementation generally begins with a call to INHERITED DoWrite so that 
the print information record is saved, if necessary. It then saves the document's . 
data. 


If your document uses the resource fork and the resource fork exists, then MacApp 
will ensure that the topmost resource file is that of the document when this method 
is called. You may want to get the reference number of the resource file at the start 
of this method if you think that some other method might change the top resource 
file. 


See the “Saving and Restoring Data” recipe in the Cookbook for details of this 
method. 


Call __ this method when you override it (by calling INHERITED DoWrite), Otherwise, 


you never call it. 
A 


ForAilViewsDo 
PROCEDURE TDocument .ForAllViewsDo (PROCEDURE DoToView(aView: TView)); 


Procedure DoToView isa procedure, usually local to the caller, that is called repeatedly by 
ForAllViewsDo and passed each of the views in turn. 


Purpose To perform an operation on all views of a document. 
The default automatically scans through the list of views and calls DoToViews once for each 
version document. 


Never override 


Sometimes call 
eee UUO 
ForAllWindowsDo 


PROCEDURE TDocument . ForAliWindowsDo (PROCEDURE DoToWind(aWindow: TWindow) ); 


Procedure DoToWind is 4 procedure, usually local to the caller, that is called repeatedly by 
ForAllWindowsDo and passed each window of this document in turn. 


Purpose This utility method is called whenever an operation must be performed on all 
windows of a document. 
. The default automatically scans through the list of documents and calls DoToWind once for 
version each window. 


Never override 


Sometimes call 
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FreeData 

PROCEDURE TDocument.FreeData; 

Purpose This method is called during a revert operation to free the document's data 
objects. 

Called by TDocument. Revert 

The default does nothing 

version 


Always override this method to free data objects that should be freed when the user chooses the 
Revert command. 


Sometimes call You may want to call this method from your implementation of TDocument Free, 
if. convenient. 


i 


FreeFile 

PROCEDURE TDcocument.FreeFile; 

Purpose is to free resources associated with the connection between a TDocument object 
and a disk file. 

Called by TDocument.Free, TDocument.SaveViaTemp, TDocument.SavelnPlace 

The default closes the appropriate forks of the file if fDataOpen or fRsrcOpen and fSaveExists 

version are TRUE. 


Sometimes override 








Rarely call 

FreeFromClipboard 

PROCEDURE TDocument.FreeFromClippoard; 

Purpose is to free a Clipboard document. 
Called by TView.FreeFromClipboard 

The default calls Free. 

version 


Sometimes override to do something other than Free. 











Never call 
GetTempName 
PROCEDURE TDocument .GetTempName (VAR fileName: Str255); 
fileName is a name for a temporary document file. 
. Purpose is to generate a random temporary filename. 
The default appends a mutated form of the time of day to the name of the document or, if the 
version . document is untitled, to the name of the application. 
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Rarely override 
Sometimes call 


A aaacasa 


IDocument 
PROCEDURE TDocument . Document (itsFileType, itsCreator: OSType; usesDataForx, usesRsreFork, 


dataOpen, rsrcOpen: BOOLEAN); 
A aaaeaii 


itsFileTy pe is the file type for the document file. 
itsCreator is the signature of the application that created the document file. 
usesDataFork indicates whether (kUsesDataFork ) or not (NOT kUsesDataFork ) the document 


uses the data fork of the file. 


usesRsrcFork indicates whether (kUsesRsrcFork ) or not (NOT kUsesRsrcFork ) the document uses 


the resource fork of the file. 


dataOpen indicates whether (kDataOpen) or not (NOT kDataOpen) the data fork of the file 
should be kept open at all times. ` 


rsrcOpen j indicates whether (kRsrcOpen) or not (NOT kRsrcOpen) the resource fork of the 
file should be kept open at ail times. 

Purpose is to initialize a TDocument object. It is usually called from the initialization 
method of customizations of TDociment. 

The default gives these values to the fields of TDocument: 

version fWindwList := NewList; 


fDocPrintHandler := NIL; 

fChangeCount := 0; 

fSavePrintIafo := FALSE; 

fSharePrintinfo := TRUE; 

fPrintInfo := NIL; 

fTitle := '1; 

fFileType := itsFileType; 

fVolRefNum := 9; 

fSaveExists := FALSE; 

Creator ;= itsCreator; 

fDataPerm := fsRdPerm; 

fRsrePerm := fsRdPerm; 

fDataOpen := dataOpen; 

fRsrcOpen := rsrcOpen; {This is meaningless when there is a 64K ROM.; 

IF NOT fDataOpen AND NOT fRsrecOsen THEN 
fSaveInPlace :* sipAskUser 

EUSE 


fSaveInPlace := sipNever; 


Never override 


Call this method at the beginning of the [YourDocument method that you write for your 


document type, and then change any values you need to change and do any 
additional initialization you require. 


OpenWindow 


PROCEDURE TDocument .OpenWindow (aWindow: TWindow) ; 
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aWindow is the window that should be opened. 

Purpose is to open the given window. 

Calied by TDocument.ShowWindows, TApplication.OpenWindow 
The default calls aWindow.Open to open the given window. 

version 


Sometimes override 


Sometimes call 








SavedOn 

PROCEDURE TDocument.SavedOn (fileName: Str255; volRefNum: INTEGER) ; 

fileName is the name of the document file. 

volRefNum is the volume reference number for the file. 

Purpose is to allow the programmer to clean up any data structures or work files to note that 
a clean save has been made. 

Called by TDocument.Save when 2 new copy of the file is being made (the normal situation). 

The default resets f{ChangeCount to 0, sets fSaveExists to TRUE, replaces fTitle and fVolRefNum 

version with the values passed in and, if fDataOpen or fRsrcOpen is TRUE, opens the 


appropriate fork. 
Sometimes override 
Never call 





SavelnPiace 


PROCEDURE TDocument.SaveInPlace(itsCmdNumber: CmdNumber; makingCopy: BOOLEAN; VAR fileName: 
Str255; volRefnum: INTEGER); 





itsCmdNumber is the command number for this save operation. 

makingCopy tells whether or not a copy of the original file is being saved. 

fileName is the name of the document file. 

volRefNum is the volume reference number for the file. 

Purpose is to allow the programmer to clean up any data structures or work files to note that 
a clean save has been made. 

Called by TDocument Save when switchToTarget is TRUE and askForFileName is FALSE. 

The default if fDataOpen and fRsrcOpen are both FALSE, deletes the target file, calls 

version SELF.FreeFile, calls SELF.MakeNewCopy, and then calls SELF SavedOn. If either 


fDataOpen or fRsrcOpen is TRUE, the default version does nothing. 


Sometimes override to save a disk-based document in place by modifying the file. You must set 
SELF.fDataPerm and SELF.fRsrcPerm to a modifiable mode in this method or 
before calling this method. 


Never call 
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SaveViaTemp 
PROCEDURE TDocument .SaveViaTemp (itsCmdNumber: CmdNumber; makingCopy: BOOLEAN; VAR fileName: 


Str255; velRefNum: INTEGER); 
ee ne ss 


itsCmdNumber is the command number for this save operation. 

makingCopy tells whether or not a copy of the original file is being saved. 

fileName is the name of the document file. 

volRefNum is the volume reference number for the file. i 
Purpose is to save the document into a new, temporary file. 

Called by TDocument.Save when a new copy of the file is being made (the normal situation). 
The default calls SELF.MakeNewCopy and then calls SELF.FreeFile if switchToTarget is TRUE. 
version It then deletes the target Cif it exists), renames the file, and calls 


TDocument.SavedOn if switchToTarget is TRUE. 
Rarely override 


Never call 
i a 


SetTitle 

PROCEDURE TDocument.SetTitle(aTitle: S$tr255); 

aTitle is the new title for the window. 
e—a i e a 
The default sets SELF.fTide to aTide and calls SetTitleForDoc for each window of the 
version document. 


Sometimes override 


Sometimes call 
eee 


ShowReverted 

PROCEDURE TDocument .ShowReverted; 

Called by TDocument.DoMenuCommand when the user chooses the Revert command and 
clicks the OK button in the dialog box that is displayed. 

The default calls ShowReverted for each view of the document. 

version 


Never override _ 

Rarely call l ; 
eee a aaae O 
ShowWindows 


PROCEDURE TDocument.ShowWindows; 
OO aaa aaaeei aaea a IAU 


Purpose is to display a documents windows on the screen. It is called when the document is 
initially opened. 
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Called by TApplication.OpenNew, TApplication.OpenOld 
The default calls OpenWindow for all windows that have fOpeninitially TRUE. 
version 


Sometimes override this method to determine in some other way what windows are initially shown. 


Never call 
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Customize: rarely 
instantiate: often 
Cali methods: usually 


The TFrame type implements the concept of a rectangular area of a window that knows how to 
scroll in either or both directions. Frames are like windows in that they can be resized and 
moved, they have a list of controls that are displayed within them, and they can have 
independent coordinate systems. TWindow is a descendant of TFrame. 


Frames are arranged in a hierarchy; each frame has a container (of type TFrame or a descendant 
type) and contents (a TList object holding frames). A frame’s fContentRect is defined in the 
coordinate system of its container. 

Ancestors: TObject, TEvtHandler, TFrame 


Fields 





fContainer: TFrame; The window or frame that contains this frame directly. 
FContentRect: Rect; The boundary relative to this frame’s fContainer. 
‘Controls: ControlHandle; The first of the controls displayed in this frame. 
fFrameList: TList; A list of frames contained in this frame. 


fIdlePriority: INTEGER; Gives a priority value for the Doldle method of this object. If not 
greater than zero, the default Idle method never calls this object’s Doldle 
method. The default Idle method calls the Doldle methods of any 
handlers with fidlePriority values greater than zero. (The Doldle methods 
are called in the order of the handler list. If you want them called in a 
different order, override TApplication.Idle.) The default value is 0. 
Inherited from TEvtHandler. 


fInCpenWindow: BCOLZAN; TRUE if the window that contains this frame is open on the screen 


‘NextHandler: TEvtHandler; The next handler in the chain of event handlers, or NIL. Note that if 
fNextContainer is not NIL, {Container = fNextHandler. This field is 
inherited from TEvtHandler. 


fParentisWindow: 3COLEAN; TRUE if this frame’s fContainer is a window object. 


fFResizeByWindow: ARRAY[VHSelect}] OF BOOLEAN; If fResizeByWindowlvhs} is TRUE and if 
fParentlsWindow is TRUE, then TWindow.ChangedSize will automatically 
adjust the botRight.vhivhs] coordinate of fContentRect. 


£ScroliBars: ARRAY'VHSelect} OF ControlHandle; The scroll bars that control the frame. 
(Scroll bars belong to the controi list of the frame's container, not the 
frame itself. Each scroll bar is a control, and controls have a refCon field. 
(See the Control Manager chapter of Inside Macintosh for more 
information.) 


fSerailiinit: Point; The standard amount to scroll in each direction. 


ww 
[$] 


rollLimit: Poinc; The maximum view coordinate that can be revealed by scrolling. By 
default this is view.fExtentRect.botRight, but the application can place a 
different value here so that the user will be able to scroll past the end of the 
view. 
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fShowSBars: BOOLEAN; If TRUE, then the frame should show its scroll bars when its window is 
: made active. i 


fShowBorder: BOOLEAN; If TRUE, call frame.DrawBorder whenever the frame is displayed, which, 
by default, does InsetRect(fContentRect, -1, -1) then FrameRect of 
fContentRect with a (1, 1) black pen. 


fView: TView; The view shown in this frame, if any. 


fViewedRect: Reet; The subset of {View that is currently visible within the frame’s 
fContentRect, in view coordinates. This is set as a side effect by each call 
to TFrame.GetViewedRect, so that if you know that GetViewedRect was 
calied after the last time the viewed rectangle could have changed, you can 
confidently use fViewedRect. Otherwise, fViewedRect may not be up-to- 
date. 


fWindow: TWindow; The window that contains this frame (possibly indirectly; this frame may 
be contained in another frame). 
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DofrackControal 
FUNCTION TFrame.DoTrackControl(localPt: Point; aControl: ContrcoiHandle; partCode;: 
INTEGER; VAR info: Eventinfo): TCommand; 








localPt is the point where the mouse pointer is located. 

aControl is a handle to the control where the mouse pointer is located. 

partCode is a number (described in Inside Macintosh) that identifies the kind of 
control. 

info is the event information record for the event that resulted in this call. 

The return is a command object that will handle the event. 

value 

Purpose is to handle a mouse press in a control. 

Called by TFrame.TrackAppControl 

The default if there is a view, calls TView.DoTrackControl. Otherwise, it returns 

version gNoChanges. f 

Rarely override You may override this method if you have controls other than ordinary 


scroll bars in the frame, but you are more likely to override 
TYiew.DoTrackControl. 








Never call 

DrawAll 

PROCEDURE Trrame.OrawAil; 

Called by TFrame.Drawinterior (to draw any frames contained in this one), 
TWindow.UpdateEvent (if TWindow.DrawaAll is called). 

The default calls fView.AboutToDraw if finformBeforeDraw is TRUE, calls Focus, calls 

version Drawinterior, and, if fShowBorder is TRUE, calls DrawBorder. 


Sometimes override this method to draw something else in the frame. 


Never call 
RES AA S ee a ee ee 


DrawBorder 

PROCEDURE Trrame.DrawBorder; . : 
hi U a 
Called by TFrame.DrawAll ' 


The defauit outlines one pixel beyond the frame using FrameRect. 
version $ 


Sometimes override 
Never call 
—. eee 


Drawlnterior 


PROCEDURE Trrame.OrawInterior; 
eaaa r U ra a 


Called by TFrame.DrawAll 
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The default Checks whether the contents of the frame are visible on the 
version screen, and if so, draws the frame’s controls; calls DrawView; and calls 
DrawAll for every frame contained in this frame. 


Rarely override 


Rarely call 
OE 
DrawView 
PROCEDURE TFrame.OrawView; _ 
Called by TFrame. Drawinterior 
The default calls fView.DisplayOnScreen to draw the view, if any of the view shows on 
the 
version | screen. 


Rarely override 
Never cali 


NT 


Focus 
PROCEDURE TFrame.Focus; 


tt PFO SS a 


Purpose This method focuses drawing on a frame. Focusing involves setting 
thePort (a QuickDraw global variable), setting the origin and clipping 
region for thePort, and installing the frame’s controls in the window. 


The default properly focuses on SELF. 
version 


Sometimes override 


Often call In general, a frame must be focused before you can draw in it, but MacApp 
automatically focuses for you before calling your view.Draw, 
command.TrackFeedback, and highlight methods. If you draw in other 
cases, you must focus first. In addition, it is important to focus before 
calling any Control Manager routines, because most of those routines draw 
on the screen. 





ForceRedraw 
PROCZIOURE TFrame.ForceRecraw; 





Purpose This method invalidates the entire content area of the frame. 
Called by TView. FrameChangedSize 

The default invalidates the entire frame. 

version 


Never override 


Often call 





HaveView 
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PROCEDURE TFrame.HaveView(aView: TView); 


a i a  rere 


aView is the view to be shown in this frame. 

T e e y A e e 

Purpose is to associate a frame with the view that is shown in the frame. Look in 
UMacApp.u2 for details of the implementation. 

Called by called by application code . ` 

The default associates aView with SELF. 

version 


Never override 


Often cali Call this method when a view is initially installed in the frame, and then 
any ime a new view is installed in the frame. 


St grep 


IFrame 
PROCEDURE TFrame. iframe (itsNextHandler: TEvtHandler; itsContainer: TFrrame; 
itsContentRect: Rect; wantHScroliBar, wantVScrollBar: BOOLEAN; wantkResizing, 
WantVResizing: BOOLEAN) ; 
ne 
itsNextHandler identifies the next handler in the chain of event handlers. If there is no 

next handler, this should be set to NIL. CThis is usually set to the container, 

or gApplication if there is no container.) 


itsContainer identifies the TFrame object that contains this frame. This is most often 
the window (an object of type TWindow, a customization of TFrame) in 
which this frame is displayed. If there is no container, this should be set to 
NIL. 


itsContentRect defines the size and position of the frame, in its container’s coordinate 
system. (That is, where the upper left corner of the container is the origin.) 
If there is no container, this frame is a window, and this value is the size of 
the window in window coordinates. 


wantHScrollBar determines whether or not the frame will have a horizontal scroll bar. Use 
kWantHScrollBar or NOT kWantHScrollBar to set this value. 


wantVScrollBar determines whether or not the frame will have a vertical scroll bar 
kWantVScrollBar or NOT kWantVScrollBar to set this value. 


wantHResizing determines whether or not the frame's fcontentRect should automatically 
be adjusted in the horizontal dimension when the containing window is 
resized. Use kHFrResize or NOT kHFrResize to set this value. 


wantVResizing determines whether or not the frame’s contentRect should automaucallv 
be adjusted in the vertical dimesnion when the containing window is 
resized. Use kVFrResize or NOT kVFrResize to set this value. 


Purpose is to do standard initialization for a frame. 
Called by TWindow.IWindow. It is also usually called when a frame is created (or, if 
you have your own type of frame, from that frame’s [YourFrame method) 
The default sets the values of the fields of TFrame to the values passed as the method's | 
version parameters. The fields tħat do not have parameter values passed in are | 


assigned as foliows: 





IF fContainer<>NIL THEN 
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fWindow:= itsContainer. fWindow; 
ELSE 

fWindow:= NIL; 
fView:= NIL; 
fControls:= NIL; 
fSerolliBars[{h]:= set to NIL or scroll bar; 
fScrollBars{v]:= set to NIL or scroll bar; 
SetPt(fSerollUnit, kStdSecroll, kStdSeroll); 
SetPt (fScrollLimit, kStdScrLimit, kStdScrLimit) ; 
finOpenWindow:= FALSE; 
fShowBorder:= TRUE; 
fParentisWindow:= FALSE; 
fShowsBars:= TRUE; 


In addition, the default version sets fFrameList to a new list with elements 
of type TFrame. 


Never override However, when you customize TFrame, you usually supplement this 
method’s action with an fYourFrame method. 


Often call If you do not customize TFrame, you call this method after you create each 
frame; if you customize TFrame, you usually call this method near the 
beginning of your [YourFrame method. 





InvelAssumingFocused 
PROCEDURE TFrame.InvalAssumingFocused(r: Rect); 





r is a rectangle in view coordinates whose displayed contents are invalid. 


Purpose This method is the same as TFrame.InvalidRect except it assumes the 
frame is already focused. It adds rectangle r to the update region for the 
view contained in this frame. 


The default calls InvalRect(newRect) (an Inside Macintosh routine), where newRect is 

version the intersection of r and the clipping region bounding box. The area 
enclosed in r is thus added to the area that will be passed to view.Draw the 
next time the frame is updated. 


Never override 





Sometimes call More often call TView.InvalidRect. 

InvalidRect 

PROCEDURE TFrrame.invalidRect(r: Rect); 

r is a rectangle in view coordinates whose displayed contents are not 
invalid. 

Purpose is to add the area enclosed in r to the update region for the view contained 


in this frame. That is combined with the visRgn to derive the area that is 
passed to view.Draw the next time the frame is updated. 


The default calls SELF.Focus and then calls InvalAssumingFocus. 
version 


Never override 
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ReveaiRect 

PROCEDURE Tframe.RevealRect (rectToReveal: Rect; minToSee: Point); 

rectToReveal is a rectangle, in view coordinates, that is to be scrolled into the frame. 
minToSee defines a part of the rectangle which is the minimum amount that is to be 


scrolled into the frame. 
a ee eT = 


Purpose This method undertakes scrolling sufficient to reveal at least minToSee of 
the rectangle rectToReveal. 


The default calculates the necessary change in the scroll position and calls ScrollBy to 
scroll 
version the frame. 


Rarely override 


Often call 
ee 


SetSBarMax 

PROCEDURE TFrame.SetSBarMax; > 

Pea a a A E 
Calied by TFrame.ViewResized 


The default calculates the maximum scroll position and calls the Inside Macintosh 
routine 

version SetCuMax to set it. It also calls ScriToSBars to adjust the frame and scroll 
bars. 


Rarely override 


Never call 
eee 


SerlToSBars 
PROCEDURE Trrame.ScriToSBars (invalWholeFrame: BOOLEAN) ; ' 
invalWholeFrame indicates whether or not the entire frame should be invalidated 
ne 
Called by - TFrame.Resize, TFrame.SetSBarMax, TFrame.ScrollBy, and 

TFrame. TrackAppControl. 


The default scrolls the frame to the current elevator position and invalidates as much 
of the 
version frame as necessary. It then calls SELF.UpdateEvent. 


Rarely override 


Rarely call 
a a ee 


SerollBy 


PROCEDURE TFrame.ScrollBy(delta: Point; inyalWholeFrame: BOOLEAN); 


delta . is the amound the frame should be scrolled, 
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invalWholeFrame indicates whether or not the entire frame should be invalidated 








Called by TFrame.RevealRect, TFrame.ScrollTo, and TrackOnce (a MacApp global 
routine). 

The default adjusts the position of the scroll bars and calls TFrame.ScriToSBars to 
scroll the 

version frame. 

Rarely override 

Rarely call 

ScroilStep 

FUNCTION TFrame.ScrollStep(vhns: VHSelect; backwards: BOOLEAN; frameSize: INTEGER): 

INTEGER; 

vhs indicates the scroll direction. 

backwards indicates whether the scroll is to the left or top (TRUE) or down or right 
(FALSE). 

frameSize is the size of the frame in direction vhs. 

The return is the amount to scroll by, in terms of points in the view. If backwards is 
TRUE, this 

value number may be negative. 

Called by TFrame.AutoScroll 

The default returns fScrollUnit in direction vhs; if backwards is TRUE, it returns the 
negative of 

version that number. 


Sometimes override 
Never call 


ScrollTo 


PROCEDURE TFrame.ScrollTo(newPos: Point; invalWholeFrame: BOOLEAN) ; 


newPos is a point in the view. 


invalWholeFrame indicates whether or not the entire frame should be invalidated 


Called by TFrame.HaveView 
The default scrolls the frame to the position indicated by the elevator 
version l i 


Never override 


Never call 


UpdateEvent 


PROCEDURE TFrame.UpdateEvent;. 


Called by TFrame.ScriToSBars and other methods. 
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The default calls TWindow.UpdateEvent. 
version 


Sometimes override 
Rarely call 
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TWindow l 


Customize: rarely 
instantiate: always 
Calf methods: rarely 


The TWindow type defines window objects sufficient for most applications. 

You generally use the global procedures NewSimple Window and NewPalette Window to create your 
windows. 

Your application’s resource file must contain an appropriate window resource. 


Ancestors: TObject, TEvtHandler, TFrame, TWindow 


Fleids 


fCanBeActive: BOOLEAN; If FALSE, the window will not become the active window. The default is 
TRUE. 


€CanBeClosed: BOOLEAN; If TRUE, the Close menu command is enabled for the window. 


fConstTitle: INTEGER; The number of characters in the window title that are constant (that is, 
not part of the document name). 


fControls: ControlHandle; The first of the controls displayed in this window. This field is 
inherited from TFrame 


fDisposeOnFree: BOOLEAN; If TRUE, TWindow.Free calls DisposeWindow. If FALSE, 
TWindow.Free calls CloseWindow. The default is FALSE. 


£Document: TDocument; The document that owns this window. 


f£DoFirstClick: BCOLZAN; If FALSE, when the window is inactive and the user clicks once in the 
window, the window is activated and the click is otherwise ignored; if 
TRUE, 2 single click activates the window and is then handled as a click in 
an active window. i 


fFrameList: TList; A list of frames contained in this window. Inherited from TFrame. 


£FreeOnClosing: BOOLEAN; Determines if this object is freed when it is closed. The default is 
FALSE. 


fIsDialog: BOOLEAN; If TRUE this is a dialog window. 


fIdlePriority: INTEGER; Gives a priority value for the Doldle method of this-object. If not 
greater than 0, the default Idle method never calls this object's Doidle 
method. The default Idle method calls the Doldle methods of any 
handlers with fidlePriority values greater than 0. (The Doldle methods are 
called in the order of the handler list. If you want them called in a different 
order, override TApplication Idle.) The default value is 0. This field is 
inherited from TEvtHandler. 


‘InOpenWindow: BOOLEAN; TRUE if the window is open on the screen. Inherited from TFrame. 


£lsActive: BOOLEAN; Whether or not this window is active. This value may differ from testing if 
the fWmegrWindow is the front window if a pending activate event that 
hasn't been processed yet. The FrontWindow value is more up-to-date. 
(See the “Window Manager” chapter of Inside Macintosh for more 
information.) 


fisResizable: BOOLEAN; If TRUE, the size box is drawn when the window is active 
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fNextHandler: TEvtHandler; The next handler in the chain of event handlers, or NIL., Generally 
the window's document. This field is inherited from TEvtHandler. 


fNormalsize: Rect; When the window is expanded to full size using the expand icon (4 new 
addition to the interface standard), this is set to the original size. 


fOpenInitially: ‘BOOLEAN; If TRUE, then this window, after it has been launched for a document, 
should immediately be opened. See the description of 
TDocument. ShowWindows in this chapter for more information. 


*PreDocname: INTEGER; The start of the name of the document in the window title relative to the 
beginning of the string as defined in the resource file. 


‘Target: TEvtHandler; The global gTarget is set to this value when the window is made active. 
£View: TView; The view shown in this frame, if any. Inherited from TFrame. 


‘ViewedRect: Rect; The subset of fView that is currently visible within the Frame’s 
fContentRect, in view coordinates. This is set as a side effect by each call 
to TFrame.GetViewedRect, so that if you know that GetViewedRect was 
called after the last time the viewed rectangle could have changed, you can 
confidently use fViewedRect. Otherwise, this may not always be up-to- 
date. This field is inherited from TFrame. 


‘WmgrWindow: WindowPtr; A pointer to the Window Manager window controlled by this TWindow 
object The WindowRecord type (see the Window Manager chapter of 
Inside Macintosh) has a refCon field, which is used to store a reference to 
the TWindow object. The refCon of fWmerWindow is ORD(SELF) + 1. 


fWouldCloseDoc: BOOLEAN; If this is TRUE and the user closes the window, the document is also 
closed. 


eee 
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Activate 
PROCEDURE TWindow.Activate (entering: BOOLEAN); OVERRIDE; 


-entering is TRUE when the window is being activated, FALSE if the window is being 
deactivated. i 
Pupose is to activate or deactivate this window, as needed. 
` Called by TApplication.ObeyEvent 
The default updates the view and then, if entering = TRUE, installs the selection, makes 
version this wiridow the front window, sets gTarget to the window's fTarget, and sets 


gDocument to the window's document SetCursor is given a chance to 
change the cursor. If entering = FALSE, the selection is deinstalled, 
gTarget is made the application object, gDocument is made NIL, and the 
cursor is set to the arrow cursor. See the source code for additional action. 


Sometimes override 


Rarely call 

ay e e a a 
Changedsize 

PROCEDURE TWindow.ChangedSize(oldBotRight, newBotRight: Point); OVERRIDE; 

Purpose is to change the size of a window. 

Called by TWindow.Open 

Originally 

declared by TFrame 

The default changes the size of the window and tells the frames to change their size 

version (according to fResizeBy Window fields). 


Sometimes override to resize frames differently. 
Rarely call 


i aaaaaaaaaaaaaaaaaaaaaaauaaassasasasastuatluaasasasatlalatuMuMlMMslMlMluM 


DowninContent 
FUNCTION TWindow.DownInContent iglobalPt: Point; VAR info: Eventinfo): TCommand; 


globaiPt is the point where the mouse went down, in global coordinates 
info is the event record for this mouse-down event. 
The return is a command object to handle the mouse-down event, or gNoChanges. 
value 
E o a raamat 
Called by TApplication.ObeyEvent 
The default figures out what part of the window contained the mouse-down point and 
gives that 
version part a chance to handle the event. If the mouse-down point wasn’t in any 


part of the window, it returns gNoChanges. 
Rarely override 
Rarely call 
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Window 
PROCEDURE TWindow.IWindow(itsDocument: TDocument; itsWmgrWindow: WindowPtr; isDialog: 
BOOLEAN; canResize, canClose: BOOLEAN); 
—— i eee eet 
itsDocument is the document that owns this window, or NIL If NIL, the window will not 

be associated with any document. 


itsWmgrWindow is the Window Manager window controlled by this TWindow object. 


isDialog tells whether or not this is a dialog window. 
canResize ` tells whether or not this window has a size box 
canClose tells whether the Close menu command should be enabled and whether 


the window has a close box. 
eee 
Called by the MacApp global procedures NewSimpleWindow and 

NewPalette Window after the new window is created and by application 

code when you make your own type of window. 


The default performs standard initialization of a window object. First, it associates the 

version window object with the Window Manager window. Second, it calls IFrame 
to do some frame-type initialization, including setting fNextHandler to 
itsDocument or, if that is NIL, to gApplication, and loading the fields 
defined for TFrame. The call to [Frame is 


IFrame (itsNextHandler, NIL, r, FALSE, FALSE, FALSE, FALSE); 
(See the description of TFrame.IFrame for more information.) 


TWindow loads the window’s fields with the values passed as parameters, 
sets the other fields, and does more initialization. See the source code for 
the specific assignments. š 


Never override However, if you customize TWindow, you usually supplement this 
i method’s action with a IYourWindow method. 


Sometimes call . 
aaaeeeaa 
Open 


PROCEDURE TWindow.Open; OVERRIDE; 


Fe eS 


Purpose is to open the window. 

Called by TApplication.OpenWindow and other methods. 

The default opens the window and gives the window’s frames a chance to open 
version themselves. $ 


Rarely override 


Rarely call ; 
eee a a a 


UpdateEvent 
PROCEDURE TWindow.Updatefvent; OVERRIDE; 
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Purpose _ This method causes an update of the entire window. The contents of a 
window are erased and redrawn. 

Originally 

declared by TFrame 

Called by TApplication.Close, TApplication.ObeyEvent, TFrame.ScriToSBars, 
TFrame.UpdateEvent, TWindow.Activate 

The default redraws the entire window. 

version a 

Rarely override 


Sometimes call 
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TView 


Customize: always 
Instantiate: never 
Cail methods: usually 


You always customize TView to create a view that displays your document's data. 


If items in a view can be cut or copied, the view must be able to handle the calls that relate to the 
Clipboard. When items of a view are cut or copied, a view object of the same type as the view is 
created to display the items in the Clipboard. 


Note: The following methods implement standard printing. They are placed in the. 
view so that you rarely need to customize TPrintHandler. The default implementation 
of each of these methods calls the corresponding TPrintHandler method to handle 
the action. (In general, you include UPrinting in your application. UPrinting 
customizes TPrintHandler for you, and it provides sufficient printing capability for 
most applications.) 


FUNCTION TView.DoBreakFollowingivhs: VHSelect; prevBreak: INTEGER; VAR 
automatic: BOOLEAN): INTEGER; 

FUNCTION TView.DeMaxPageNumber: INTEGER; 

PROCEDURE TView.DoCalcViewPerPage; 

PROCEDURE TView.DoDrawExtraFeedback (area: Rect); 

FUNCTION TView.DoMaxPageNumber: INTEGER; 

PROCEDURE TView.DoPagination; 

PROCEDURE TView.DoPrinterChanged; 


Ancestors: TObject, TEvtHandler 


Fields 
— eee 
tCanSelect: BCOLEAN; If this is TRUE, this view can contain a selection and a mouse press in this 

view automatically deactivates any companion view (relevant only for 

subviews installed in a TCatView object). Set this in your TYourView 

method. 


flccument: TOocument; The document shown by this view. 
fExtentRect: Rect; The bounds of the view, in view coordinates. 


‘Frame: TFrame; The frame in which this view is displayed or, if the view is not displayed, 
NIL. This view is fFrame.fView or is contained in fFrame.fView. 


rh 
ay 


ELinactive: 4LState; The highlighting to use if the window is inactive: hlDim or hlOff. 


s8iDesired: HLState; What the highlighting should be at the current time: either hlOn if the 
window is active or fHLInactive if the window is inactive. 


view. Draw is called. 
fMinBotRight: Point; The minimum value for the bottom-right point of the view. 


fOidScroil: Poinc; When the view is not displayed in a frame, the fScrollOffset of the view’s 
: last frame is automatically stored here. 


Parent: TView; Either NIL or the view that contains this view. Gf not NIL, the value is the 
same as fNextHandler.} 


Final page 10-5] 


Object and Method Reference MacApp Programmer's Guide 


fPrintHandler: TPrintHandler; The object that handles printing for this view. Unless you install 


fRes: Point; 


a specific print handler for the view (almost always using 4 print-handler 
object type defined in UPrinting), this field points to the global “null” 
print handier, gNullPrintHandler. 


The view resolution, in spots per inch. 


fShowBorders: BOOLEAN; Whether or not to draw borders of the view on the screen; generally 


fShowExtraFeedback: 


useful for debugging views whose sizes may change. 


BOOLEAN; Whether or not any extra feedback will be drawn when your Draw 
method is called. The feedback may be page breaks, headings, view 
borders, and so on. 


fSizeDeterminer: ARRAY[VESelect] OF SizeDeterminer; Specifies how the horizontal and 


vertical bounds of the view are to be determined. 


fTarget: TEvtHandler; Relevant only for subviews installed in a TCatView object. 


fViewPerPage: Point; 


fWouldMakePICTSerap: 


fWrittenToDeskScrap: 





Final 


The default size, in view coordinates, of the part of the view that fits in the 
interior of a printed page. (That.is, the page size minus the margins, in 
view coordinates.) 


BOOLEAN; If TRUE, then MacApp’s WriteToDeskScrap method will 
generate PICT-type data in the desk scrap, which can then be pasted into 
other applications (MacPaint, for example). 


BOOLEAN; Relevant only for a view installed in the Clipboard; this flag tells 
whether or not the view has written its data to the desk scrap. 


page 10-52 


MacApp Programmer's Guide Object and Method Reference 


Activate i 
PROCEDURE TView.Activate(wasActive, beActive: BOOLEAN) ; 


wasActive is TRUE if the view is currectly active. 
beActive is TRUE if the new state is active. 
_ ee 
Called by TFrame.Activate (to activate the view) and TFrame.Close (to deactivate 
the view). 
The default calls DoHighlightSelection if wasActive <> beActive. Calls 
version DoCheckPrinter if beActive = TRUE. 


Rarely override 
Rarely call 


re 


AboutToDraw 
PROCEDURE TView.AboutcToDraw; - 
oe eee 
Purpose This method exists to do any preparation that must be done before 
drawing the view, and that was put off. An example is with a desk scrap 
view, where the desk scrap is not actually copied into the view until the view 
is about to be displayed. This method is never called unless 
fInformBeforeDraw is TRUE. 


Called by TFrame.DrawaAll, TView. WriteToDeskScrap 
The default does nothing 
version 


Sometimes override If you override this method, you implement it so that it does any deferred 
data preparation necessary before drawing the view. You would do this 
when the preparation is time-consuming, and might be unnecessary Cif the 
view is never drawn) or might otherwise be redone several times before the 
view is drawn. 


Never call : 
- OOO 


AdjustExtent 


PROCEDURE TView.AdiustExtent; 


——_- ee 


Called by j TView.FrameChangedSize; TView.ShowReverted, 
TDeskScrapView.AboutToDraw, and TStdPrintHandler.PrinterChanged. 


The default calls ComputeExtent and uses fSizeDeterminer to compute the new size. 
version 


Sometimes override this method because the standard size-determining algorithm is 
inadequate for your application. 


Sometimes call 


aaa emaema a 


AttachPrintHandler 


PROCEDURE TView.AttachPrintudandier (itsPrintdandler: TPrintYandler); 


itsPrintHandler is the print handler for this view. 
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i a 


Purpose is to install the print handler in a view. 
Called by TPrintHandler,IPrintHandler 

The default sets fPrintHandler to itsPrintHandler. 
version 


Sometimes override You override this method generally because you have initialization that 
must wait until the print handler is installed. 


Sometimes call - 


arree a e a 


CaicMinExtent 

PROCEDURE TView.CalcMinExtent (VAR minExtent: Rect); 

minExtent is the smallest possible size of the view at this time. 

a a ee L 
Purpose is to return the current minimum possible extent of a view. 

Called by TView.ComputeExtent 

The default changes the MinExtent to fMinBotRight unless fSizeDeterminer is 

version sizeFixed. (It checks each dimension separately, so you can have the size 


fixed horizontally and not vertically, or vice versa.) If the view’s size is 
fixed, the value of fExtentRect is returned. 


Sometimes override this method to calculate the allowable minimum extent in some other 
way. 


Never call 





ChildGrew 


PROCEDURE TView.ChildGrew(wnoGrew: TView): 





whoGrew refers to the view that initially changed size. (Views can have several 
*children,” which are views displayed within the “parent” view. See the 
description of TCatView in this chapter for more information.) 





Purpose This method should react to a change in size of a view displayed within this 
view. 

Called by TView.SetExtent 

The default does nothing. 

version 


Sometimes override You should override this method whenever you have a view (a parent 
view) that displays one or more views within its extent (child views). 
Generally, you must make the parent view large enough so it can contain all 
its children. 


Never call 





ContainsClipType 
FUNCTION TView.ContainsClipType (aType: ResType): BOOLEAN; 
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aType identifies a particular Clipboard data type. 
The return tells whether or not the Clipboard contains the requested type. 
value 
— eee o UO 
Called by CanPaste to find out whether the Clipboard contains à given Clipboard 
data type. It is only called when this view is a Clipboard view. 
The default calls GetScrap to find out if the desk scrap contains the given Clipboard 
version data type. If it does, the method returns TRUE; otherwise, it returns 


FALSE. This is appropriate only if the Clipboard data is only in the desk 
(public) scrap. 


Often override In your implementation, retum TRUE if your view contains the given type 
of Clipboard data. Otherwise, return FALSE. 


Never call 


——— a ener 


DoBreakFollowing 
FUNCTION TView.DoBreakFollowing(vhs: VHSelect; prevBreak: INTEGER; VAR automatic: 
BOOLEAN): INTEGER; f 


in eaaa OUO 


vhs whether the requested page break is in the vertical or horizontal direction. 

prevBreak the position of the previous page break in direction vhs. 

automatic whether the page break was specified by the user (FALSE) or derived 
automatically (TRUE). i 

The return is the location of the new page break, in view coordinates, in direction 

value vhs. Note that page breaks in the vertical dimension are drawn as vertica! 


lines, those in the horizontal dimension as horizontal lines. 


Purpose Given the location of the previous page break, this method finds the 
location of the next page break. 

Called by methods of TSidPrintHandler 

The default calls fPrintHandler.BreakFollowing. That method returns the location of 

version the page break that follows the page break located at prevBreak, in 


direction vhs; The fPrintHandler.BreakFollowing method returns 
automatically = TRUE if the page-break is thought of as an “automatic” 
rather than a “manual” (user-specified) one. Note that page breaks in 
dimension v are drawn as vertical lines, those in dimension h as horizontal 
lines. (TStdPrintHandler.BreakFollowing supports only automatic page 
breaks. The automatic parameter in BreakFollowing is provided so you 
can override it to support manual page breaks.) 


Sometimes override this method if your page breaks are not equidistant. 
Rarely call 
eee 


DoCalcViewPerPage 
PROCEDURE TView.DcoCalcViewPerPage; 
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Purpose This method calculates how much of the view fits on a page. The value 
obtained, a point in view coordinates, is installed in view.fViewPerPage. 

Called by methods of TStdPrintHandler 

The default calls fPrintHandler,CalcViewPerPage. 

version 


Sometimes override Override this method when you want to set the page size to some value 
other than that calculated by the UPrinting version of this method. 


Never call 





DoDrawExtraFeedback 
PROCEDURE TView. DoDrawExtraFeedback (area: Rect); 


area identifies the part of the view in which the extra feedback needs to be drawn 


Purpose This method can draw anything that is added to a view in addition to the 
interpreted data that is drawn in view.Draw and the highlighting drawn in 
view.DoHighlightSelection. In general, it is used to draw printing-specific 
additions for screen display only, such as page breaks and page numbers, 
but it may also be used to draw other special structures such as rulers. 


Called by TView.DisplayOnScreen after itsView.Draw (and possibly 
itsView.DoHighlightSelection) is called. 


The default — The default implementation checks the value of ShowExtraFeedback and, 
version if it is TRUE does the following: 
e Sets the pen to gBreaksPenSrate. 
a If fShowBorders is TRUE, frames fExtentRect, thus showing the page 
breaks at the bounds of the view (as in MacDraw). 
e. Calls fPrintHandler. DrawExtraFeedback. 
e. Resets the pen state. 


Sometimes override You can override this method to draw any extra screen feedback that is not 
drawn by the view.Draw methods, and that you want drawn at this time 


Never call . 
eee aaa aa a a U 


DoHighlightSelection 


PROCEDURE TView.DotignlightSelection(fromHL, toXL: HLState); 


fromHL indicates the current (old) highlight state. Either hlOn, hiDim, or hIOff. 


toHL indicates what the new highlight state should be. Either hlOn, hiDim, or 


hlOff. 
a i 


Purpose This method changes the highlighting of a selection. MacApp methods 
call this method when the view is activated, deactivated, and updated. 
Application methods also occasionally call it. If the window is being 
deactivated, or is updated when inactive, toHL is set to fHLInactive. If the 
window is being activated or is updated when active, toHL is set to hiOn. 


Called by TView.DisplayOnScreen, TView.Activate 
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The default. does nothing 
version 


Usually override Your override method should highlight or remove highlighting 
depending on the values of the parameters. The type of highlighting 
depends on the kind of item that is to be highlighted. 


Sometimes call Generally, you call it when the selection changes. (You don’t have to call 
this method in the update cycle; MacApp calls it for you. Focus before 
calling this method.) 


z ; 


DoKeyCommand 
FUNCTION TEvtHandler.DoKeyCommand(ch: CHAR; aKeyCode: INTEGER; VAR info: Eventin£e): 


TCommand; 


ch is a character typed at the keyboard. 

aKeyCode is the ASCII code for the character ch. 

info is the event information record that contains the key event 

The return is a command object. 

value 

reer 

Purpose This method handles key commands, which are simply events resulting 
from keyboard typing. 

Originality TEviHandler. TView does not override this method. 

declared by 

Called by TApplication.ObeyEvent 

The default calls DoKeyCommand for the next handler in the list of handlers. If there 

version is no next handler, the default method returns gNoChanges. 


Sometimes override If you override this method, you should return a command object that can 
respond appropriately to the character. See the description of 
TCommand in this chapter for more information. (For simple editing, 
this method is implemented in the TEView unit. See the “Using TEView” 
recipe in the Cookbook or the TTETypingCommand section of this 
chapter for more information.) 


Never call 

DoMaxPageNumber 

PUNCTION TView.DoMaxPageNumber: INTEGER; 

The return is the maximum page number that would be printed if the entre view were 
value printed at the time of the call. 

Purpose This method called at printing time, should return the maximum page 


number that would be printed ifthe user requested that the all pages be 
printed. This would be important if the view has data only up to a certain 
point, such as in a spreadsheet or in MacDraw. 


Called by UPrinting methods. 
The default calls fPrintHandler.MaxPageNumber. 
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Sometimes override 








Never call 

DoMenuCommand 

FUNCTION TView.DoMenuCommand({aCmdNumber: CmdNumber): TCommand; OVERRIDE; 
aCmdNumber is the command number for the menu command chosen by the user. 
The return is a command object or gNoChanges. l 

value 

Purpose is to handle menu commands particular to a TView view. 

Originally TEvtHandler 

declared by 

Called by TApplication.MenuEvent when the view is gTarget. (Actually, a 


TYourView object would be gTarget; if you override 
TView.DoMenuCommand, you always end it with a call to INHERITED 
DoMenuCommand, so this method is called if 
TYourView.DoMenuCommand doesn’t handle the command.) It is also 
called if gTarget is a previous handler in the chain of event handlers and 
none of the previous handlers takes care of the command. (The chain of 
INHERITED DoMenuCommand calls eventually reaches 
TEvtHandler.DoMenuCommand, which ends with 

fNextHandler. DoMenuCommand.) 


The default handles the commands involving printing (which are passed on to the 
version print handler, if there is one), and Show Borders (debugging only). 
Often override You override this method when you define menu commands that apply to 


your view. If you do not handle the menu command, you should return 
gNoChanges, and call INHERITED DoMenuCommand. 


Call when you override this method by calling INHERITED 
DoMenuCommand. Otherwise, you never call this method. 


DoMouseCommand 
FUNCTION TView.DoMouseCommand (VAR downLocalPoint;: Point; VAR info: EIventinfo; VAR 
hysteresis: Point): TCommand; : 


downLocalPoint indicates where, in view coordinates, the mouse pointer was located at the 
ume the button went down. 

info contains an information record MacApp generates from the event record 
the Event Manager created for this mouse event. 

hysteresis is passed in as gStdHysteresis. You can change it to another value. 

The return ` is a command object or gNoChanges. 

value 
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= L O I ee eee 
Purpose This method is called when the mouse button goes down within the frame 
- ‘that shows this view. (This is not called when the mouse button goes down 
in the menu bar, in the borders of the window or frame containing the 
view, or outside the window.) It returns an object of some type which is 
descended from TCommand, which is called repeatedly as the mouse 
moves and when the button comes up. , 


Called by TFrame. TrackInContent 

The default returns-gNoChanges, which is a value that can stand in for a command 

version object. The effect of that is to wait until the mouse button comes up and to 
do nothing. 

Usually override When you override this method, you generally return a command object 


that tracks the mouse and takes appropriate action as it moves and when 
the mouse button comes up. The details of mouse command objects are 
discussed under “Handling mouse events” in the Cookbook. 


Never cali ; 
ee 


DoPagination 
PROCEDURE TView. DoPagination; 


eee 


Purpose This method is called to recalculate the set of page breaks for a view. 
Called by TStdPrintHandler.PrinterChanged 

The default calls fPrintHandler.RedoPageBreaks. 

version 


Sometimes override You might override this method to force redrawing of the view after page 
breaks are recomputed. In that case, you would call INHERITED 
DoPagination first. 


Rarely call 
| . 

DoPrinterChanged 
PROCEDURE TView. DoPrinterChanged; 
Purpose This method should do whatever is necessary to react to the changed 

i printer metrics. 
Called by TStdPrintHandler.CheckPrinter when the printer metrics have changed. 
The default calls fPrintHandler.PrinterChanged. 
version 


Sometimes override If you override this method, you should do whatever is necessary to react 
to changes to the printer metrics, such as adjusting the view extent if 
changes in the printer affect the page layout. (TTEView reimplements’ 
this.) 


Never call 


eee 
DoSetCursor 
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FUNCTION TView.DoSetCursor(localPoint: Point): BOOLEAN; 





locaiPoint is the current location of the mouse pointer in view coordinates. 
The return whether or not the view sets the cursor. 

value 

Called by TApplication.TrackCursor (which itself is called repeatedly when the 


mouse button is up) when the mouse pointer (sometimes called a cursor) is 
over the view. It can change the pointer to a different (nonarrow) shape 
or track the movement of the mouse, possibly providing feedback. 


The default returns FALSE and does nothing else. When DoSetCursor returns FALSE; 
version TApplication.TrackMouse sets the mouse pointer to an arrow. 
Often override Applications most commonly override this method to change the shape 


of the mouse pointer to a shape more appropriate than an arrow. See the 
QuickDraw chapter of Inside Macintosh for details on mouse pointers 
(called cursors in that chapter). If you do change the mouse pointer 
shape, be sure to return TRUE so TApplication.TrackCursor doesn’t 
change the mouse pointer back to an arrow. Some applications use 
DoSetCursor to track the mouse when the mouse button is up. 





Never call 

DoSetUpMenus 

PROCEDURE TView.DoSetupMenus; OVERRIDE; 

Purpose is to adorn, enable, or disable all menu commands handled by the view. 
Originally 

declared by TEvtHandler 

Called by TApplication.SetupTheMenus and when an immediate descendant’s 


method calls INHERITED DoSetupMenus. This method is called before 
any menu is displayed when the menus may have changed since the last 
time it was called, or from the idle loop, again when the menus may have 
changed since the last time it was called. 


The default sets up the menu commands handled by TView.DoMenuCommand and 
version tells the view to set up its print handler. 
Often override You always override this method when you override 


TView.DoMenuCommand, and you never override it if you do not 
override TView.DoMenuCommand. You use this method to set up any 
menu commands handled by TYourView.DoMenuCommand. Begin your 
override method by calling INHERITED DoSetUpMenus so MacApp can 
set up the menu commands it handles. Then, you use the global 
procedures Enable and EnableCheck to enable any menu commands that 
can currently be used. (EnableCheck, like Enable, can enable or disable 
menu commands. EnableCheck can also add or remove a check mark next 
to a menu item.) You can also adorn menus in other ways. See the 
“Changing Menu Appearance and Function” recipe in the Cookbook for 
more detailed information. 


Call when you override this method by calling INHERITED DoSetupMenus. 
Otherwise, you never call this method. 
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DoTrackControl 
FUNCTION TView.DoTrackControl (localPt: Point; aControl: ContrelHandle; partCode: 
INTEGER; VAR info: EventInfo): TCommand; 


localPt is the point where the mouse pointer is located. 

aControl is a handle to the control where the mouse pointer is located. 

partCode is a number (described in Inside Macintosh) that identifies the kind of 
control. 

info is the event information record for the event that resulted in this call. 

The return is a command object that will handle the event. 

value 

i aaa aaas 

Purpose is to handle a mouse press in a control. 

Called by TFrame.DoTrackControl 

The default returns gNoChanges and does nothing else. 

version i 


Sometimes override You always override this method if you have controls other than ordinary 
scroll bars in the view. 











Never call 

Draw 

PROCEDURE TView.Draw(area: Rect); 

area indicates the part of the view (in view coordinates) that needs to be 
updated. 

Purpose This method should draw the view. 

Called by TView.DisplayOnScreen, TView. WriteToDeskScrap 

The default does nothing 

version 

Always override Your override method should draw the view, possibly using the area 


parameter to optimize drawing, See the “Views” section of the Cookbook 
for more information on drawing. 


Never call 





FreeFromClipboard 
PROCEDURE TView.FreerromClipboard; 





Called by AbandonUndoClipboard when this Clipboard view can be freed. Note 
that this is not done immediately when another Clipboard view is created, 
the old Clipboard view stays in existence until the operation that created 
the new one can no longer be undone. FreeFromClipboard frees this view 
and anything else that should be freed at the same ume. 
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The default checks whether there is a Clipboard document of which this is a view and, 
version if there is one, calls fDocument FreeFromClipboard. Otherwise, it simply 
frees the view. 


Sometimes override You need to override this method when you have objects other than the 
document and the view that must be freed. 


Never call f 
eaea a aa a U 
GivePasteData - : 
FUNCTION TView.GivePasteData(aDataHandle: Handle; dataType: ResType): LONGINT; 
aDataHandle is a handle provided for data that will be pasted. 
dataType is the type of Clipboard data that the caller wants to receive. 
The return is, if positive, the number of bytes of data obtained. If negative, it is an 
value OSErr value indicating that no data could be obtained. . See the Scrap 
Manager chapter of Inside Macintosh for the OSErr values that may be 
returned. 
—_—_—_— a 
Called by application (or building block) code when the user gives a Paste 


command. This method passes data from the Clipboard by placing the 
data in the space referred to by the given handle. It then gives the amount 
of data as the return value of GivePasteData. If it is not possible to obtain 
data of the given data type, the method returns a negative number, which 
is interpreted as an OSErr. 


The default calls GetScrap (a Scrap Manager function) to obtain data of the requested 

version type from the desk scrap. If debugging was on when MacApp was compiled 
and an error is returned, a message is printed in the Debug window. 
Otherwise, the error is simply passed back to the caller. 


Usually override You need to override this method to paste data from the view (when it is a 
Clipboard view). In general, every application that implements cutting 
and pasting of its own data overrides this method. In those cases, the data 
is generally not in the desk scrap, and you must interpret and respond to 
the GivePasteData request yourself. See the “Paste” recipe in the 
Cookbook for details on doing this. 


Often call 
a E a a a o 


InvalAssumingFocused 
PROCEDURE TView.InvalAssumingFocusedir: Rect); 


r is a rectangle in view coordinates whose displayed contents are invalid. 
Purpose This method is the same as TView.InvalidRect except that it assumes the 
frame is already focused. 
The default calls fFrame.invalAssumingFocused(newRect), where newRect is the 
version intersection of rand the view’s extentRect. The area enclosed in r is thus 
added to the area that will be passed to view.Draw the next time the frame 
is updated. 


Never override 
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IvalidRect 

PROCEDURE TView.InvalidRect(r: Rect); 

r is an area of the view, in view coordinates. 

Purpose This method is called by application methods and by MacApp to indicate 
that some part of the view must be redrawn. 

Called by TView.ShowReverted and application methods 

The default ; if the view has a frame and r is within the view’s extent, calls 

version fFrame.InvalidRect. 

Never override 

Usually call 

View 


PROCEDURE TView.IView(itsParent: TView; itsDocument: TDecument; itsExtent: Rect; 
itsHDeterminer, itsVDeterminer: SizeDeterminer; itsCanSelect: BOOLEAN}; 


itsParent identifies a view which contains this view, or is NIL. 

itsDocument identifies the document whose data is interpreted by this view. 

itsExtent gives the limits of the view, in view coordinates. l 
itsHDeterminer specifies how the size of the view is determined in the horizontal direction. 
itsVDeterminer specifies how the size of the view is determined in the vertical direction. 
itsCanSelect indicates whether or not this view can contain the selection, if this is part 


of a TCatView object. 


Purpose This method initializes a TView object in a standard way. 
The default loads fields of TView with the values passed in through the parameters. In 
version addition, fWrittenToDeskScrap and fInformBeforeDraw are set to FALSE, 


and the fMinBotRight parameter is set to a value depending on 
fSizeDeterminer. Qf fSizeDeterminer = SizeFixed, fMinBotRight is set to 
itsExtent.botRight. Otherwise, fMinBotRight is set to (1,20).) 


Never override However, you almost always supplement its action with an TYourView 
method. 

Always call this method from your TYourView method, usually near the beginning of 
that method. 

SetExtent 

PROCEDURE TView,Set©&xtent (newExtent: Rect); 

newExtent is the new size of the view. 

Called by TView AdjustExtent 

The default adjusts the size of the view. If this is a parent view, it calls 
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version 


Rarely override 
Sometimes call 


TView.ChildGrew. 


if fSizeDeterminer is fixed in both directions. 





WriteToDeskScrap | 


PROCEDURE TView.WriteToDeskScrap; 





Called by 


The default 
version 


Often override 


TApplication.AboutToLoseControl when the Clipboard contains an 
application view and the application is about to lose control. This can 
happen when the application terminates, when the user activates a desk 
accessory, or when the user switches to a different application using the 
Switcher. 


if fWouldMakeP!CTScrap is TRUE, converts the data shown by this 
Clipboard view to data that can:be handled by the desk scrap, and writes 
the data to the desk scrap data. 


You must override this method for views that may be Clipboard views (in 
general, any view that can have parts cut, copied, or pasted) where you 
want to be able to pass data in a form other than PICT-type through the 
desk scrap to other applications. Call PutDeskScrapData (a MacApp 
global procedure) or PutScrap (a Scrap Manager procedure) to put the 
data in the desk scrap. Those procedures may be called repeatedly for 
different kinds of desk scrap. See the “The Clipboard” section of the 
Cookbook for details on this method. ` 


when you override this method. You call INHERITED WriteToDeskScrap 
to get PICT-type desk scrap data created by MacApp (if 
view.fWouldMakePICTScrap is TRUE). Otherwise, you never call this 
method.. 


A a 
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TPrintHandler 


Customize: rarely (You usually use UPrinting, which customizes this type.) 
instantiate: never 

Call methods: sometimes 

TPrintHandler exists as a “stub” for UPrinting. Few applications deal with it directly. 


You generally include UPrinting in your application. That unit customizes TPrintHandler to give 
enough printing capabilities for almost all applications. 


In general, if you need to change some aspect of printing, you reimplement a printing method of 
TView rather than customizing TPrintHandler or TStdPrintHandler. 


Ancestors: TObject, TEvtHandler 


Flelds 





fDeviceRes: Point; Formal printer resolution in spots per inch. 


fEffectiveDeviceRes: Point; The true effective spots per inch of the printer. This is larger than 
the fDeviceRes value if reduction is in effect, smaller if enlargement is in 
effect, and the same if neither is in effect. (Reduction and enlargement 
are controlled by the user through the standard Page Setup dialog box.) 


fPageAreas: ARRAY {ImageSpace] OF PageAreas; Metrics in the view and the device space for 
printing. 


fView: TView; The view for which printing is handled. 
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Note: TPrintHandler includes a number of methods that exist primarily to be called 
from methods of TView. They are as follows: 


FUNCTION TPrintHandler.BreakFollowingivhs: VHSelect; prevBreak: INTEGER; 
VAR automatic: BOOLEAN): INTEGER; 

PROCEDURE TPrintHandler.CalcViewPerPage(VAR amtPerPage: Point); 

PROCEDURE TPrintHandler.CheckPrinter; 

PROCEDURE TPrintHandler.DrawExtrafeedback (area: Rect); 

PROCEDURE TPrintHandler.LocatePageInterior (pageNumber: INTEGER; VAR loc: 

Point); 

FUNCTION TPrintHandler.MaxPageNumber: INTEGER; 

PROCEDURE TPrintHandler. PrinterChanged; 

PROCEDURE TPrintHandler.RedoPageBreaks; 

PROCEDURE TPrintHandler,SetPageInterior(pageNumber: INTEGER); 

PROCEDURE TPrintHandler.SetPageOffset (coord: Point); 


The TPrintHandler versions of these methods do nothing. TStdPrintHandler 
overrides them so they take the action expected in the TView methods that call them. 
See the description of TView in this chapter for more information on what these 
methods do. If you need to change their actions, you generally do it by overriding the 
TView methods rather than these methods. (Even if you create your own print handler 
type, you usually do that by customizing TStdPrintHandler, not TPrintHandler.) See 
the implementation of TTEView in UTEView for an example. 


IPrintHandlier 

PROCEDURE TPrintHandler.IPrintHandler(itsView: TView); 

its View is the view for which this is a print handler. 

Purpose This method initializes a print handler. 

Called by TStdPrintHandler.1StdPrintHandler 

The default sets the fView field of the print handler to itsView and calls [EvtHandler to 
version do additional initialization. i 

Never override However, if you customize TPrintHandler directly (which very few 


applications do), you generally supplement the action of this method with 
an [YourPrintHandler method. In that case, you should call [PrintHandler 


from your method. 


Call this method only if you customize TPrintHandler directly. 





WouldPrintRect 
FUNCTION TPrintHandler.WouldPrintRect(r: Rect): BOOLEAN; 





r is a rectangle in view coordinates. 

The return indicates whether or not the given rectangle is within the part of the view 
that is 

value projected onto the page currently being printed. 

Purpose is to check if the rectangle is within the page that is currently printing. The 
purpose is for optimization of view.Draw, which uses RectisVisible to find 

; out what it actually needs to draw at this time. 
Called by RectlsVisible when gPrinting is TRUE. 
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Originally TPrintHandler 
declared by 

The default returns TRUE. 
version 


Sometimes override In general, if you customize TPrintHandler, you should override this 
method, to allow optimization of printing. (That is very rarely done, 
however.) 


Never call However, as noted, when gPrinting is TRUE, a call to RectIsVisible is 
passed to this method. 
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Customize: usually. 
Instantiate: never 
Cali methods: rarely 


TCommand objects fall into two general categories: command objects and mouse trackers. The 
Cookbook includes a number of recipes dealing with different types of command objects and 
mouse trackers. In general, you override Dolt, Undolt, Redolt and possibly Commit for 
command objects and trackers that change the document, while you override TrackConstrain, 
TrackFeedback, and TrackMouse only for mouse trackers. 


Command objects and mouse trackers that do not change the document do not need Undoit, 
Redolt or Commit. In fact, you may never create a command object for many commands that do 
not change the document; in those cases, you can (optionally) carry out the action of the 
command from DoMenuCommand, DoMouseCommand, DoKeyCommand, DoCommandKey 
or another method that retums a command object. (In that case, return gNoChanges.) 


Ancestors: TObject 


Fields 





fCanUnde: BOOLEAN; Whether or not this command can be undoné. The default is TRUE. 


£CausesChange: BOOLEAN; Whether or not this command changes the document referred to by 
the command’s fChangedDocument field. This defaults to TRUE. When 
this is TRUE, the document is automatically marked as changed when this 
command is done. (if the command is undone, the document’s change 
count is automatically decremented and, if the command is redone, the 
change count is incremented again.) 


fChangedDocument: TDocument; The document that may be changed by the command. This 
defaults to gDocument. 


fChangesClipboard: BOOLEAN; Whether or not this command changes the Clipboard. This 
defaults to FALSE and should be set to TRUE for cut or copy commands 
that change the Clipboard. 


fCmdNumber: CmdNumber; The command number associated with the command 


£ConstrainsMouse: BOOLEAN; When this is set to TRUE, this command’s TrackConstrain method 
is called as the mouse moves. This defaults to FALSE. 


fTarget: TEvtdandler; The target to set before calling Undolt or Redolt. In other words, the 
value of gTarget when this command was initially given. 
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Commit 
PROCEDURE TCommand.Commit; 





Purpose is to do anything necessary to make the effects of a command permanent. 


Called by TApplication.CommitLastCommand, which is called when the command 
can no longer be undone or redone (usually when a new undoable 
command is chosen, when the document is closed, or when the 
application is terminated). It is not called if the command was left 


undone. 

The default does nothing. 

version 

Often override This method is most commonly used to implement filtered commands or 
with commands that delete items from the document's data set, in which 
the deleted items are not freed until the command can no longer be 
undone. 

Rarely call 





Dolt, Redolt, Undoit 
PROCEDURE TCommand.DoIt; 
PROCEDURE TCommand,Redolt; 
PROCEDURE TCommand.Undolt; 





Purpose These methods are called to do, undo, and redo a command. Dolt is 
called when the command is initially done; Undolt is called when the user 
picks the Undo command an odd number of times; Redolt is called when 
the user picks the Undo command an even number of times. Dolt and 
Redolt carry out the action of the command (generally, they both call the 
same methods to do the command, although Redolt may have to change 
the selection or otherwise act to restore the state of the document at the 
time the command was originally done). Undolt reverses the action of the 


command. 

Called by TApplication.PerformCommand (Dott), 
TApplication.DoMenuCommand CUndolt and Redolt) 

The default i does nothing 

version 

Usually override These are the methods that generally carry out (and undo) the action of 


the command. The only command objects that may not override these 
methods are mouse trackers and commands that do not change the 
document or those that cannot be undone. 


Almost never call The only likely exception is that your Redolt method might call Dolt. 





ICommand 

PROCEDURE TCommand.ICommand(itsCmdNumber: CmdNumber) ; 

itsCmdNumber is the command number associated with this command. 
Purpose is to initialize fields of TCommand. 
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Called usually from the initialization methods for the immediate descendants of 
‘ TCommand. 

The default makes these assignments: 

version 


fCmdNumber := itsCmdNumber; 
fCanUndo := TRUE; 
fCausesChange := TRUE; 
fChangedDocument ;:= gDocument; 
fConstrainsMouse :* FALSE; 
fChangésClipboard := FALSE; 
fTarget := NIL; 











Never override You usually supplement its action with an TYYourCommand method. 

Call this method as part of command initialization. 

TrackConsirain 

PROCEDURE TCommand. TrackConstrain(anchorPoint, previousPoint: Point; VAR nextPolar: 

Point); 

anchorPoint gives the position of the mouse pointer, in view coordinates, when the 
mouse button went down. 

previousPoint gives the position of the mouse pointer the last time this method was 
called, in view coordinates. 

nextPoint gives the current position of the mouse pointer, in view coordinates. 

Purpose This method is provided so you can constrain the mouse movement in anv 
way your application requires. It is used only in mouse trackers. 

Called by TFrame.TrackInContent (a method you never deal with directly) when 
command.fConstrainsMouse is TRUE. 

The default does nothing. 

version 


Sometimes override this method to change the value of nextPoint. See “Handling mouse 
events” in the Cookbook for further discussion of mouse trackers. 


Rarely call 





TrackFeedback 


PROCEDURE TCommand.Trackfreedback (anchorPoint, nextPoint: Point; turnItoOn, 
mouseDidMove: BOOLEAN) ; 





anchorPoint gives the position of the mouse pointer the last time this method was 
called, in view coordinates. 

nextPoint gives the current position of the mouse pointer, in view coordinates. 

turnItOn indicates whether the feedback is to be turned on (TRUE) or turned off 
(FALSE). 

mouseDidMove is TRUE if the mouse moved since the last time TrackFeedback was called 
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Purpose is to provide on-screen feedback for the user while the mouse is being 
tracked (that is, while the mouse button is down and a mouse tracker object 
exists). 

Called by TFrame.TrackInContent 

The default provides “rubberband” feedback: a shadowy box between anchorPoint 

version and nextPoint. 

Often override this method to provide more appropriate feedback while the mouse is 


tracked’ See “Handling mouse events” in the Cookbook for further 
discussion of mouse trackers. 


Rarely call 





TrackMouse 
FUNCTION TCommand..TrackMouse (aTrackPhase: TrackPhase; VAR anchorPoint, previcusPoin:, 
nextPoint: Point; mouseDidMeve: BOOLEAN): TCommand; 





aTrackPhase indicates the current phase of the mouse tracking process: trackPress when 
the mouse button first goes down, trackMove while the mouse moves, and 
trackRelease when the mouse button comes up 


anchorPoint gives the position of the mouse pointer, in view coordinates, when the 
mouse buton went down. If you change this value, the new value is passed 
to you the next time this method is called. 


previousPoint - gives the position of the mouse pointer the last time this method was 
called, in view coordinates. 


nextPoint gives the current position of the mouse pointer, in view coordinates. 
Although you can change this value, it is better to use TrackConstrain to 
control mouse movement. 


mouseDidMove is TRUE if the mouse moved since the last time TrackFeedback was called. 
See the discussion below. 

The return is the mouse tracker that will be used in succeeding calls. You generally 

value return SELF, although applications may sometimes return a different 


mouse tracker object. 
ae re ee te 


Purpose is to allow you to carry out any actions (other than feedback or mouse 
constraint) that depend on the movement of the mouse or on the track 
phase. 

Called by TFrame.TrackinContent when the mouse button first goes down, as the 

_ button moves, and when the mouse button comes up. 

The default retums SELF, in effect doing nothing. 

version 
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Often override 


Never call 





Final 


this method to take application-specific action. You should not assume 
that the mouse should be considered to have moved the first time this is 
called with aTrackPhase as trackMove. The phase is set to ttackMove when 
the mouse moves more than the hysteresis value. SELF.TrackConstrain 
may set the mouse position back so that no movement should be 
considered to have occurred. The value of mouseDidMove should be 
tested to determine if the mouse should be considered to have moved. See 
“Handling mouse events” in the Cookbook for further discussion of mouse 
trackers. 
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TStdPrintHandler 


Customize: sometimes 
Instantiate: often 
Call methods: rarely 


This object type is defined in UPrinting. You must have UPrinting in your USES statement to use 
TStdPrintHandler. 


TStdPrintHandler provides printing sufficient for most applications, It can print multiple 
documents (from the Finder), handle the Print, Print One, and. Page Setup menu commands, and 
handle draft printing, spooled printing (including spool-a-page/print-a-page), undoing of style 
changes, programmatical setting of page margins, and programmatical setting of the starting 
page number. 


Methods of TView call methods of the print handler installed for the view (generally a 
TStdPrintHandler object). If you want to change some printing behavior, it is generally easier to 
Override the TView method than to custome TStdPrintHandler. 


Ancestors: TObject, TEvtHandler, TPrintHandler 

Fields 

fFinderSetup: BOOLEAN; When the user requests printing from the Finder, whether the Page Setup 
dialog box should be presented. 


fFinderJobDialog: BOOLEAN; When the user requests Printing from the Finder, whether the Print 
Job dialog box should be presented (making it seem like Print) or-should 
not (making it seem like Print One), 


fincludefFrame: BOOLEAN; Whether to draw a frame around the interior of the page when printing, 
usually you only want this to be TRUE when you're debugging. 


fLastCheckedPrinter: LONGINT; The time that the printer chosen with the Chooser desk 
accessory and this print handler’s information on Printer metrics were last 
known to be in harmony. The value is obtained from the Event Manager 
TickCount function. 


-MinimalMargins: BOOLEAN; If TRUE, page margins are maintained such that exactly the complete 
printable area of the page is used. 


‘PageStrips: Point Tells how many strips of pages there are: fPageStrips.h is the number 
horizontally, and fPageStrings.v is the number vertically. 


fdPrint: Handle; A handle to a 120-byte record that holds MacPrints’s data. It is actually of 
type THPrint, a MacPrinc type. 


fPrintPageNumpers: BOOLEAN; Whether or not to print a page number at the bottom of each page. 
This will usually be TRUE when you're debugging, FALSE under normal 
circumstances. 


fPrinterDev: INTEGER; MacPrint’s device number for the printer; use this for getting font metrics 
in device coordinates. 


fShowBreaks: BOOLEAN; TRUE if page breaks should be displayed. 
fShowPageNumbers: BOOLEAN; TRUE if page numbers should be shown on the screen. 


fSquareDots: BOOLEAN; If TRUE, then in the initial instance, use 72-by-72 resolution on the 
ImageWriter printer. If FALSE, use 80-by-72. 


fStartPage: INTEGER; The page number for the top left corner of the view. 
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ETopToBottom: BOOLEAN; Whether or not pages are taken from the view in vertical strips. In other 
words, TRUE means page 2 is below page 1; FALSE means page 2 is to the 
right of page 1. 





Note: TStdPrintHandler includes a number of methods that exist primarily to be 
called from methods of TView. They are as follows: 


FUNCTION TStdPrintHandler.BreakFolliowing(vhs: VHSelect; prevBreak: INTEGER; VAR 
automatic: BOOLEAN): INTEGER; OVERRIDE; 

PROCEDURE TStdPrintHandler.CalcViewPerPage (VAR amtPerPage: Point); OVERRIDE; 

PROCEDURE TStdPrintHandler. LocatePagelInterior (pageNumber; INTEGER; VAR lac: 
Point); OVERRIDE; _ i : 

PROCEDURE TStdPrintHandler.PrinterChanged; OVERRIDE; 

PROCEDURE TStdPrintHandler.RedoPageBreaks; OVERRIDE; 

PROCEDURE TStdPrintHandler.DrawExtraFeedback (area: Rect); 

FUNCTION TStdPrintHandler.MaxPageNumber: INTEGER; OVERRIDE; 

PROCEDURE TStdPrintHandier.SetPageInterior (pageNumber: INTEGER); OVERRIDE; 

PROCEDURE TStdPrintHandler.SetPageOffseticoord: Point); OVERRIDE; 


See the description of TView in this chapter for more information on what these 


methods do. If you need to change their actions, you generally do it by overriding the 
TView methods rather than these methods. 
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DoCheckPrinter 
PROCEDURE TStdPrintHandler.CheckPrinter; OVERRIDE; 


Called by '  TView.DoCheckPrinter 

Originally TPrintHandler 

declared by 

The default checks the printer metrics and prepares the document for printing with 
version this printer. 


Rarely override 


Never call l Kng 


DoPrintingCommand 
FUNCTION TStdPrintHandler.DoPrintingCommand{aCmdNumber: CmdNumber}: TCommand; 
OVERRIDE; f 

$ 
aCmdNumber is the command number for the menu command chosen by the user. 
The return is a command object or gNoChanges 
value 
eee UO 
Purpose This method is called to handle those commands whether or not the 

related view is in the target chain. ` 

Called by | TDocument. DoMenuCommand 
Originally TPrintHandler 
declared by 
The defauit handles the commands Page Setup, Print, and Print One. 
version 
Rarely override You might override it to implement some different command similar to 


Print, such as Print Table, Print Graph, or Print to File. In that case, you 
should end your method by calling INHERITED DoPrintingCommand. 


Never call 


——_—___——__—- ee; 


DoSetUpPrintingMenus 

PROCEDURE TStdPrintHandler.DeSetupPrintingMenus; OVERRIDE; 

Purpose ‘This method sets up the commands handled by DoPrintingCommand. 
Originally 

declared by TPrintHandler 

Rarely override You override this method if and only if you override 


DoPrintingCommand. In that case, you should begin your method by 
calling INHERITED DoSetupPrintingMenus. ë 


Never call ; 
; 


EachBreak 


PROCEDURE TStdPrintHandler.EachBreak (vhs: VHSelect; includeLast: BOOLEAN; PROCEDURE 
DoToBreak(loc: INTEGER; automatic: BOOLEAN)); 
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vhs is a direction. 
includeLast determines whether or not the trailing edge of the view should be 
included. 
DoToBreak is a procedure, usually local to the caller, that is called once for each page 
l break in the chosen dimension. 
Purpose - of this utility method is to do carry out an action for each page break. 
Called by TStdPrintHandler.CalcPageStrips, 
TStdPrincHandler. DrawExtraFeedback, TSrdPrintHandler.InvalBreaks 
The default iterates through all page breaks in the dimension given by vhs; the trailing 
version edge of the view (the right or bottom edge) is given as the final break if 


includeLast is TRUE. The procedure DoToBreak is called once for each 
page break in the chosen dimension. 


Sometimes override 
Sometimes call 











EachPage 

PROCEDURE TStdPrintHandler.EachPage (PROCEDURE DoToPage(pgNum: INTEGER; ptRect: Rect)); 
DoToPage is a (usually local) procedure that will be passed each page in turn. 
Purpose This utility method iterates through all pages of the view, calling 


DoToPage for each one in turn. This is not used when printing, but rather 
for page-related screen feedback on the screen. 


Never override 


Sometimes call 











GetBreakCoord l 

PROCEDURE TStdPrintHandler.GetSreakCoordivhs: VHSelect; whichBreak: INTEGER; VAR loc: 

INTEGER) ; 

vhs is a direction. 

whichBreak is the sequence number for one of the page breaks in direction vhs 

loc is a returned value giving the location, in view coordinates, of the page 
break whichBreak. 

Purpose is to return the coordinate of the page break specified by WhichBreak in 
dimension vhs. 

The default returns the required coordinate. For example, GetBreakCoordiv, 5, 

version loc) will return, in loc, the horizontal coordinate of the vertical line 


(page break) that marks the boundary between the area of the view that will 
be mapped into the fourth vertical strip of pages and the area of the view 
that will be mapped into the fifth vertical strip of pages. 


Rarely override 


Final page 10-76 


MacApp Programmer’ s Guide Object and Method Reference 


Sometimes call 


IStdPrintHandler 

PROCEDURE TStdPrintHandler.IStdPrintHandler(itsView: TView; itsSquareDots: BOOLEAN); 

itsView is the view that will be printed by this print handler. 

itsSquareDots whether or not square dots (tall adjusted) instead of rectangular dots 
should be used, by default, when printing on the ImageWriter printer. 

The default initializes the print handler and installs it in the view; if itsSquareDots is 

version TRUE, then the default print record for the ImageWriter will use square 


dots (tall adjusted) rather than rectangular ones; this sacrifices a bit of 
resolution but ensures that text and graphics that line up on the screen also 
always line up properly on the printed page. 


Never override 


Often cali 
eee a UUO 


InvalBreaks 
PROCEDURE TStdPrintHandler.InvalBreaks; 


Purpose This method invalidates (forces redrawing) of page breaks on screen 
Never override 


Sometimes call 


eee reaa UA 


PoseJobDialog 

PROCEDURE TStaPrintHandler.?oseJobDialog(VAR proceed: BOOLEAN); 

proceed whether or not the user wants the job to continue 

Purpose This method displays the Print Job dialog box on the screen. 
Never override — 

Rarely call 


ee 


PosePageSetupDialog 


FUNCTION TStdPriathandler.PosePageSetupDialog(VAR cancelled: BOOLEAN): TCommand; 


cancelled whether or not the user pressed the Cancel button in the dialog box. (If the 
user pressed OK, cancelled is FALSE.) 
The return is a command object that can handle any changes indicated by changes in 
value the Page Setup dialog box. 
si , Š an 
Purpose ` -is to handle a Page Setup command. 
Called by TStdPrintHandler.DoPrintingCommand when the user chooses the Page 


Setup menucommand. 


The default presents the standard Page Setup dialog box and produces a command - 
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version object to process the changes. (If cancelled is TRUE, the command object 
is gNoChanges.) The default command object can handle Undo. 


Rarely override 
Rarely call 





PosePrintDiclog 
PROCEDURE TStdPrintHandler.PosePrintDialog; 





Purpose When doing foreground printing, this method displays a dialog box 
allowing the user to proceed, pause, or cance! the print job and, in the 
case of Finder printing, to cancel all printing. 


Rarely override 





Rarely call 

PrintFromFinder 

FUNCTION TStdPrintHandler.PrintFromfinder: BOOLEAN; OVERRIDE; 

The return indicates whether or not printing has been successfully completed. 

value 

e—a r e e oa 

Purpose This method handles printing from the Finder. 

Called by TStdPrintHandler.Print when the command number is cFinderPrint. 

The default handles the entire printing process, including showing a dialog box 

version allowing the user to cancel printing. The return value is TRUE unless 
printing is canceled. 

Originally 

declared by TPrintHandler 


Rarely override 
Never call 


i ee 
SetMargins 


FUNCTION TStdPrintHandler.SetMargins; : 
rn ne 


Called by TStdPrintHandler.RedoPageBreaks 
The default installs the desired page margins. 
version 


Rarely override 


Never call 
SSN ac NC NE ee E AE E a ee a 


ShowDocBeingPrinted 
` PROCEDURE TStdPrintvandler.ShowDocSeingPrinted(entering: BOOLEAN); 
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A aaaea r aaaeeeaa 


entering indicates whether screen feedback should be put up (TRUE) or taken down 
(FALSE). i ‘ i 

RL 

Purpose This method puts up or takes down screen feedback that identifies which 


document is currently being printed. This is used only for Finder printing. 
Never override 
Rarely call 
i a o 
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TList 


Customize: rarely 
instantiate: often 
Call metheds: often 


TList is defined in UList. 


This object type is used in MacApp to store objects and is otherwise provided for your 
convenience. You do not have to use TList objects. 


In general, you store objects of a single type in a TList object, and when you retrieve an object, you 
coerce the result into a variable of the type you need. 


Ancestor: TObject 


Fields 





fDeletions: INTEGER; The number of deleted elements in the list. These have value 
kDeletedElement; fSize always reflects the number of real elements (that is, 
without counting these deleted elements). Other objects must not write 
directly to this field. (You can read its value, though.) 


fEachLevel: INTEGER; The number of Each calls in progress. Other objects must not write 
directly to this field. 


fFirstOffset: LONGINT; Contains the number of bytes of named fields before the first element. 


Equal to SIZEOF(SELF). Other objects should neither read nor write to this 
field. 


£Size: INTEGER; Holds the number of elements in the list. 
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Ai 
FUNCTION TList.At (index: INTEGER): TObject; 

















index is the index number of the element you want to retrieve (counting from 
one). 

Purpose is to return a specific element from a list. 

The default returns the requested element. Range checking is only done when the 

version compile flag qRangeCheck is TRUE. 

Rarely override = 

Often cali 

Delete 

PROCEDURE TList.Delete(item: TObject); 

item is a reference to an object 

Purpose is to delete a specific element from the list. 

The default searches the list for the first reference to the object referred to by item. 

version It deletes the first reference. The item is not freed. If there are additional 


references to the same item in the list, they are not deleted. If the item is 
found, this method reduces fSize by one. 


Rarely override You might override this method to delete all references to the object 
referred to by item or to free the deleted object. 








Often call 

DeleteAll 

PROCEDURE TLlist.DeleteAll; 

Purpose is to delete all elements in a list. 

The default sets fSize to 0. This deletes all elements from the list but does not free 
version objects. 


Rarely override 
Often call 


EU Sse it ery ye ae 








Each 

PROCEDURE Tlist.iacn (PROCEDURE DoToItem(item: TObject)); 

DoToltem is a procedure (usually local) that is passed each element of the list in turn. 
Purpose is to apply procedure DoToltem to every element in the list. 

The default , calls the procedure DoToltem repeatedly, passing each element of the list 
version to that procedure in turn. The actual parameter is typically a procedure 


whose argument is a descendant of TObject. If DoToltem calls InsertLast, 
the newly added element will not be passed to DeToltem. If DoToltem 
calls InsertFirst or DeleteAll, the result is unpredictable. 
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Rarely override ` 
Often call 





at 


rst 
FUNCTION TList.First: TObject; 





The return is the first element in the list 
value 





Purpose is to return the first element in a list. 


The default returns the first element in the list, or NIL if there is no first element. 











Often call 

FirstThat 

FUNCTION TList.FirstThat (FUNCTION TestItem(item: TObject): BOOLEAN): TObject; 

TestItem is a function, usually local to the caller, which returns TRUE when some 

- condition is met. l 

Purpose is to return the first element that fulfills some condition as determined by 
the function Testem. 

The default calls Testitem once for each element of the list, in order, until Testtem 

version returns TRUE. It then completes and returns the element that satisfied the 


test. If none satisfied the test, the method returns. NIL. The actual 
parameter is typically a function whose argument is a descendant of 
TObject. If Testltem calls InsertLast, the newly added element will not be 
enumerated, If Testltem calls InsertFirst, Delete, or DeleteAll, the results 
are unpredictable. 








Rarely override 

Often call 

[List 

PROCEDURE TList.IList; 

Purpose This method should be called after you create a new list to initialize the list. 

The default initializes the list, setting fSize to 0. 

version 

Never override If you customize TList, you might supplement its action with an [YourList 
method. 

Usually call Sometimes, though, you call the global procedure NewList (documented 


with this object type, not in Chapter 9), which calls this method for you. ` 
You shouid never call this twice for the same list. 
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a a a 


. InseriFirst 
PROCEDURE TList.InsertFirst(item: TObject); 


Meee ye Aer 


item is an object reference. 
rrr a a 
Purpose is to insert a new element as the first in a list. 

The default inserts a reference to the item as the new first element of the list. The 

version index of the new item is 1. All other elements are moved over one. (The 


old first element is not deleted; it is now the second element.) The value of 
fSize is increased by one. If the compile flag qDebug is TRUE and 
SetEltType was called, the item’s type is checked to make sure it is of the 
list's defined element type. (That is only possible if the application and 
MacApp were compiled with debugging on. See Chapter 11, for more 
information. 


Rarely override 


Often call 
eee 


insertLast 

PROCEDURE TList.InsertLast (item: TObject); 

item is an object reference. 
eee 
Purpose is to insert a new element as the last element in a list. 

The default inserts a reference to the item as the new last element of the list. The index 
version of the new item is fSize. (The old last element is not deleted: it is now the 


next-to-last element.) The value of {Size is increased by one. If the 
compile-flag qDebug is TRUE and SetEltType was called, the item’s type is 
checked to make sure it is of the list’s defined element type. (That is only 
possible if the application and MacApp were compiled with debugging on. 
See Chapter 11, “MacApp Debugging Facilities,” for more information. 


Rarely override 


Often call 
eee 


NewList 
FUNCTION NewList:TList; 
eee 
Purpose This procedure is provided for convenience. It creates an object of type 

TList, calls IList to initialize it, and returns the object. 


This is a global procedure. It is documented here because it is important 
only for TList objects. 


in ere 


RemoveDeletions 
PROCEDURE TList,RemoveDeletions; 
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Purpose This method removes deleted items from a list. Items deleted by Delete 
i : while an Each operation is in progress repldced, and they are counted in 
the fSize value, but their old place in the list is held by the value 
kDeletedElement. This method actually removes those elements. 


Never override 
Rarely call 
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= TTEView 


Customize: sometimes 
Instantiate: often 
Call methods: sometimes 


TTEView is a customization of TView representing a TextEdit record. (TextEdit is the simple text 
editing facility built into the Macintosh ROM.) 


The purpose of a TEView is to make TextEdit function properly in a MacApp environment, to 
supply features like like scrolling, printing, page breaks, and command handling. 


Ancestors: TObject, TEvtHandler, TView 


Flelds 


Si i fi epee 


tAcceptsChanges: BOOLEAN; Set to FALSE to have text which will not accept any change, such as 
text on the Clipboard or, perhaps, received mail 


Font: INTEGER; The font to use. 
EHTE: TEHandle; A handle to the actual TextEdit object. 


£TypingCommand: TTETypingCommand; The current text edit typing command relating to this 
record, if any. 


fXeyCmdNumber: CmdNumber; The buzzwords menu command number used to obtain the string 
‘Typing. 

fMargin: Point; The horizontal and vertical insets of the TextEdit destRect from the view 
extent. 


£MaxChars: INTEGER; The maximum number of characters to accept into the text edit record. 
The default is MAXINT; if you want to limit the maximum characters to 
fewer than MAXINT, you can change this value. 


£Size: INTEGER; The font size to use. 
fStyle: Style; The font Style to use. 
fText: Handle; The text in the TEHandle. 


fTextHasChanged: BOOLEAN; Whether or not text has changed since last change was responded to 


fTextWidth: INTEGER; The width, in view coordinates, allocated to the text (as opposed to the 


borders). 
a es E 
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Free 
PROCEDURE TTEView.Free; OVERRIDE; 





The default frees the text edit record, then frees SELF. 
version 

Originally TObject 

declared by 


Sometimes override You override this method only if you create a descendant of TTEView that 
has the only references to additional objects or other identified variables. 


Always call this method when you are done with a TTEView object. 





ITEView 


PROCEDURE TIEView. ITEView(itsParent: TView; itsDocument: TDocument; itsText: Handle; 
itsTopLeft: Point; itsKeyCmdNumber: CmdNumber; itsSideMargin: INTEGER; itsTopMargin: 
INTEGER; itsWidth: INTEGER; itsHeight: INTEGER; itsFont: INTEGER; itsSize: INTEGER; 
itsStyle: Style; itsHDeterminer: SizeDeterminer; itsVDeterminer: SizeDeterminer: 
itsMaxChars: INTEGER); 





itsParent is the view containing this view. Use NIL unless this is a subview of a parent 
catView or equivalent. 


itsDocument is the document owning this TTEView. It can be NIL, if the view belongs to 
a documendess window. 


itsText is a handle to a text edit record for storing the text. It can be NIL, in which 
case a new handle will be allocated. 


itsTopLeft gives the coordinates of the top left corner of the TTEView, in view 
coordinates, This is normally (0, 0) unless this is a subview. 


itsKeyCmdNumber is the command number that represents typing. You should normally give 


cTyping. 

itsSideMargin defines the width of the margin on the left and right sides, as a number of 
pixels, 

itsTopMargin defines the width of the margin on the top of the view, asa number of 
pixels. ' 

itsWidth gives the width of the actual text, as a number of pixels. This value plus 
twice the sideMargin value gives the width of the view. 

itsHeight gives the initial height of the view. This value is automatically changed, if 
needed. 

itsFont gives the initial font number. To be sure the font is present, you can use 
ApplFont. 

itsSize defines the initial point size for the type. 

itsStyle defines the initial font style to use. You generally give the empty set (ID. 

itsHDeterminer defines how the width of the view is to be determined. 

itsVDeterminer defines how the height of the view is to be determined. 

itsMaxChars specifies the maximum number of characters allowed; use kUnlimited for 


unlimited (kUnlimited actually sets the value at MAXINT, 32767). 
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The default initializes a TTEView object. 
version : 


Never override 


Call this method to initialize the view whenever you create a TTEView object. 





Final page 10-87 


Object and Method Reference MacApp Programmer’ s Guide 
TTECommand 
Customize: rarely 


instantiate: rarely 
Cail methods: rarely 


TTECommand is the root object type that defines a command that adds characters to or delete 
characters from a text edit view. The other commands in UTEView are descendants of 
TTECommand. 


TTECommand defines a number of methods, but they are not described here. See the UTEView 
source for details about the methods if you need more information. 
Ancesiors: TObject, TCommand 


Fieids : 


fHTE: TEHandle; The same as fTEView’s fHTE; duplicated here for code efficiency. 


fNewEnd: INTEGER; The end location in the text record of the new text that is added by the 
command, if any. 


fNewStart: INTEGER; The beginning location in the text record of the new text that is added by 
the command, if any. 


fNewText: Handle; A handle to the characters added by the command, if any. 
fOldEnd: INTEGER: The end of the selection just before the command was done. 
fOldStart: INTEGER; The beginning of the selection just before the command was done. 


fOldText: Handie; If fOldStart is the same as fOldEnd (that is, the old selection was an 
insertion point) this will be NIL. For Cut and Copy commands, this will 
also be NIL, to avoid duplicating the text that is accessible through the 
TEScrap. For typing and paste commands, this will provide a temporary 
home for the characters that make up the old selection. 


TEView: TTEView; The text edit view operated on by this command. 





P 
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TCatView 


Cusfomize: rarely 
instantiate: sometimes 
Call methods: always 


A TCatView object is a view constructed by concatenating several component subviews. You 
should make the subviews disjointed: Your subviews must restrict their drawing within their own 
extentRects, so one view does not draw in the area allocated to adjacent views. (Do not do this by 
setting the clipping region, as that will cause problems with other drawing.) 


Most TCatView methods serve simply to pass call on to the constituent subviews, which are called 
the catView’s children, 


Ancestors: TObject, TEvtHandler, TView 


Fields 
A 
fChildren: TList; These are the subviews (children) contained in the TCatView object. Each 


element must be a descendant of TView; all of the child views operate in 
same coordinate space as the parent view. — 


fCurrentChild: TView; The currently-active subview. 


Caution: Any child view of a catView that performs an undoable command 
must make sure that the command's fTarget field points to the responsible 
view. 

—_--—_———— 


Note: Because TCatView methods often just pass method calls to the component 
subviews, these methods are not explained as fully as those of other object types. You 
generally override methods in the subviews rather than the TCatView object. See the 
descriptions of these methods under TView for more complete information: 
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Activate 
PROCEDURE TCatView.Activate(wasActive, beActive: BOOLEAN); OVERRIDE; 





























wasActive is TRUE if the view is currectly active. 

beActive is TRUE if the new state is active. 

The default passes the Activate call on to component children and, upon entry, sets 
version the window’s fTarget field to fCurrentChild. 

Originally TView 

declared by 

Sometimes override 

Never call 

AddChiid 

PROCEDURE TCatView.AddChild(viewToAdd: TView); 

viewToAdd is the new child view. 

The default adds a new element to fChildren and, if appropriate, adjusts the values of 
version fCurrentChild, fTarget, and the window’s fTarget. 

Originally TView 

declared by 

Never override 

Always call l this method if you have a TCatView object. 

ChildGrew 

PROCEDURE TCatView.ChildGrew(whoGrew: TView); OVERRIDE; 

whoGrew identifies one of the component views. 

The default reacts to a change in size if one of the component subviews has had its size 
version changed. 

Originally TView 

declared by © 

Sometimes override 

Never call 

DoMouseCommand 


FUNCTION TCatView.DoMouseCommand (VAR downLocalPoint: Point; VAR info: EventInfo; VAR 
hysteresis: Point): TCommand; OVERRIDE; 





downLocalPoint indicates where, in view coordinates, the mouse pointer was located at the 
ume the button went down. 


info contains an information record MacApp generates from the event record 
the Event Manager created for this mouse event. 


hysteresis is passed in as gStdHysteresis. You can change it to another value. 
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The return is a command object or gNoChanges. 
value i i 
aaa aaaea 
The default checks fCanSelect, checks if the click is in the current child, and otherwise 
version dispatches the mouse press to the other subviews (calling WouldTakeClick) 
so they can claim the mouse press. 
Originally TView 
declared by 
Sometimes override 
Never call = 
aaar aaaea eee 
EachChild 


PROCEDURE TCatView. fachChild (PROCEDURE DoTochildView(aView: TView; VAR done: 
BOOLEAN) ); OVERRIDE; 


OO eee 


DoToChild is a (usually local) procedure that is passed each subview in turn. 

The default performs DoToChildView on each of the subviews until done is set TRUE. 
Originally TView 

declared by 

Never override 

Often call 

_ OOO aaaea LUZ 
Free 


PROCEDURE TCatView.Free; OVERRIDE; 


= ee 


The default frees the component subviews then frees SELF, 
version 

Originally Tview 

declared by 

ICatView 


PROCEDURE TCatView. [CacView(itsDacument: TDecument; itsExtentRect: Rect; 
itsHDeterminer, itsVDeterminer: SizeDeterminer; itsCanSelect: BOOLEAN); 


itsDocument is the document shown in this TCatView object, itsDocument can be NIL, 
: in which case the view has no documents 

itsExtentRect gives the limits of the view, in view coordinates, 

itsHDeterminer specifies how the width of the view is determined in the horizontal 

direction. 

itsVDeterminer specifies how the height of the view is determined in the vertical direction. 

itsCanSelect whether or not this view can contain the selection. 

The default initializes a TCatView object in a standard way. It begins by calling [View. 

version (See the description of TView.IView in this chapter for more information.) 

Originally TView 
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declared by i 
Never override However, if you customize TCatView you almost always supplement its 


action with an TYourCatView method and call this method from the 
begining of TYourCatView. 


Sometimes call 











SetCurreniChild 

PROCEDURE TCatView.SetCurrentChild(aChildView: TView); 

aChildView is one of the subviews of this TCatView object 

The default installs aChildView as the TCatView object’s current subview (child), 

version appropriately adjusting [CurrentChild, target variables and fields, and the 
selection. 

Originally ` TView 

declared by 

Rarely override 

Usually call this method if you have a TCatView object. 
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TDialogitem 
Customize: rarely 


instantiate: never 
Cail methods: rarely 


TDialogitem is an object type representing an item in a dialog—usually one of the actual items in 
the dialog’s itemList in the resource file, but also sometimes a pseudoitem, such as a cluster of 
radio buttons. 


Ancestors: TObject, TEvtHandler, TView 


Fleids : 
St a ee a 
fitemHandle: Handle; The handle to the item. 

fItemNumber: INTEGER; The item number in the dialog resource file of the item; 0 if none. 


fType: INTEGER; Obtained from the resource file. , 
eaaa raaa 
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DoFilterEvent 
PROCEDURE TDialogItem.DoFilterEvent (VAR anEvent: EventRecord; VAR itemHit: INTEGER; 
VAR handledIt: BOOLEAN; VAR doReturn: BOOLEAN); 





anEvent is the current event record. 

itemHit should be ignored. 

handledit should be ignored. 

doReturn should be ignored. . 

Purpose This method is for modal dialogs only. It allows dialog items to filter 
events, _ 

Called by the dialog’s FilterProc method (indirectly by TDialog.TalkToUser). 

The default gives the item a chance to filter out certain undesirable events and to 

version modify others. 


Rarely override 


Never call 
re ee 


IDialogitem 


PROCEDURE TDialogItem.IDialogItem(itsItemNumber: INTEGER; itsParent: TDialogView; 
itsCanSelect: BOOLEAN); 
ee 


itsItemNumber is the item number for this item. 


itsParent is the TDialogView object in which this TDialogltem object is installed. 
(TDialogView is a descendant of TCarView.) 


itsCanSelect indicates whether or not this view can contain the selection. 
ne 
The default initializes a TDialogitem object. If itsParent is not NIL, it calls 

version itsParent.AddChild to install this view in the TDialogView object. 


Never override 


Rarely call 
aeaaaee eee a Iau 


ltemSelected 


FONCTION TDialogItem.ItemSelected(anItem: INTEGER; VAR handledIt: BOOLEAN; VAR 
dGoneWithDialog: BOOLEAN): TCommand; 
rE 


anitem should be ignored. 

handledIt should be ignored. 

doneWithDialog should be ignored. . 

The return 

value is 2 command object that can handle the action. 
Purpose is to give an item a chance to handle a mouse press in a dialog item. 


Normally dialog items handle only themselves, but a radiò cluster is an 
example of an exception to this rule—the radio cluster object handles a 
mouse press in any of its constituent radio buttons. 
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Called by TDialog View. DoltemSelected 

The default retums gNoChanges. 

version 

Rarely override 

Rarely call 
ee 
SetVisibility a 

PROCEDURE TDialogltem.SetVisibility (makeVisible: BOOLEAN); 

makeVisible tells whether this item should be made visible (TRUE) or invisible _ 

(FALSE). 
ae aaao a‘ 
Purpose is to let an item to be dynamically made visible or invisible. 

The default makes the item invisible if makeVisible is FALSE and makes the item visible 
version if makeVisible is TRUE. , 


Never override 


Rarely call 

__ eee 
Validate 

PROCEDURE TDialogItem.Validate (VAR succeeded: BOOLEAN); 

succeeded indicates whether or not the item is valid. 

Purpose is to respond when the dialog view containing this item sends a call 


requesting that the dialog item inspect itself to make certain that all is well. 
If the item fails a validity check the method returns succeeded as FALSE. If 
all is well, the method returns succeeded as TRUE. Typically, only key 
handlers can fail, because they find the text that has been typed into them 
not to their liking. 


Calied by TDialogView. Validate 
The default : returns TRUE. 
version 


Rarely override 


Rarely call 
LE aaa aaam 
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TDialogView 
Customize: usually 


Instantiate: usually 
Cail methods: usually 


A dialog view is a view representing a modal or modeless dialog. Some, but not necessarily all, of 
the dialog's items are stored in the field {Children (inherited from TCatView), which can also 
have in it views that are not in the resource file, such as TRadioCluster objects. 


You do not usually have to (and generally should not) explicitly add items to the fChildren list; 
elements are added to it automatically by methods like TPlae View: DefineRadioCluster and 
TDialogView. DefineNumberText. 


Ancesiors: TObject, TEvtHandier, TView, TCatView 


Flelds 





fAllowReturn: BOOLEAN; Whether or not to allow the return character as an ordinary input 
character. If FALSE (the default), the return is interpreted as a synonym 
for pressing the default button Cif any). 


f£ButtonBox: Rect; A rectangle surrounding the default button, drawn to provide the user with 
screen feedback (a thick oval) indicating which button is the default button. 


fCanBeClosed: BOOLEAN; Whether or not the dialog window will be closable. This field is relevant 
only for modeless dialogs obtained from the resource file. 


fChildren: TList; The subviews (called children) contained in this TDialogView object. 
Each element must be a descendant of TView; all of the child views, and all 
child views operate in the same coordinate space as the parent view. This 
field is inherited from TCatView. 


€CurrentChild: TView; The currently active subview. This field is inherited from TCatView. 


fD£ltButton: INTEGER; The item number of the default button of the dialog, considered pushed 
when Return or Enter is pressed. 


fDialogPtr: DialogPtr; The DialogPtr used to provide storage. 


fDisposeOnFree: BOOLEAN; Whether or not, when the. dialog view is freed, the corresponding 
storage for the DialogPtr should be disposed of. This field is set by 
IDialogView depending on whether storage is provided. 


fHookItem: INTEGER; The item number of the “hook item,” a vacant item provided in the 
Resource definition of the dialog to allow for outlining the default button. 


fIsResizable: BOOLEAN; Whether or not the dialog window will be resizable. This field is relevant 
only for modeless dialogs obtained from the resource file. 


£KeyHandler: TkeyHandler; The current element of a circular linked list of key handlers; 
incoming keystrokes are sent to this field. Tab and Shift-Tab actions are 
determined by marching forward or backward through the linked list to 
determine the next element to activate. 


fModal: BOOLEAN; TRUE for a modal dialog; FALSE for a modeless dialog. 
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DefineNumberText 
FUNCTION TDialogView.DefineNumberText (item: INTEGER; minValue, maxValue: INTEGER; 
maxDigits: INTEGER): TNumbérText; 








item is the item for which you are defining number text 

minValue is the minimum value allowed 

maxValue is the maximum value allowed. 

maxDigits is the maxium number of digits allowed. 

The return is the dialog item that handles numerical text 

value - 

Purpose is to create a dialog item of type TNumberText; which can validate 
numerical entries. 

The default declares that the given item in the dialog is an EditText item whose value is 

version constrained to be an INTEGER, not exceeding maxDigits in length, whose 


value must fali within the range given by {minValue, maxValuel. 
Never override 
Often call © 





DefineRadioCluster 
FUNCTION TDialogView.DefineRadioCluster(firstIitem, lastItem, selectItem: INTEGER): 


TRadioCluster; i 
firstitem the first item in the cluster of radio buttons. 
lastItem the last item in the cluster of radio buttons. 

selectItem is the item that should be initially selected. 

The return is a TRadioCluster object. 

value 

Purpose is to define a set of dialog items as a radio cluster. 

The default declares that items firstltem through lastitem are all radio buttons that 
version are to behave as a cluster of radio buttons and the selectltem parameter 


should be initially selected. Such a cluster is automatically maintained by 
MacApp code so that one and only one radio button can be selected, and 
selecting a new radio button deselects the old selection. 


Never override 


Always call this method when you want to declare a cluster of radio button. 





OoBuittonPushed 


PROCEDURE TDialogView.DoButtonPushed(anItem: INTEGER; VAR succeeded: BOOLEAN); 
—_————— eee 


anItem is one of the dialog items. 

succeeded whether or not the dialog should be dismissed. 

A OL ELL LE TI e 
Purpose - This method handles the pressing of a bution in a dialog. 
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Called by TDialogView. DoltemSelected 

The default gets the value of succeeded by calling Validate if anltem is OK; otherwise, 

version - it sets succeeded to TRUE. When succeeded is TRUE, the dialog is 
dismissed. 

Often override this method to determine which button was pushed by examining anltem 
and then take appropriate action. 

Rarely call l 

DoDrawExtraFeedback g . 

PROCEDURE TDialogView,DoDrawExtraFeedback (area: Rect); OVERRIDE; 

The default because a dialog view can’t be printed, this method does not dispatch the 

version method call to subviews, unlike the default handling of the ancestor’s 
method, TCatView. DoDrawExtraFeedback. 

Originally "  TView 

declared by 

Sometimes override 

Never call 

DoFilterEvent 


PROCEDURE TDialogView.DoFilterEvent (VAR anEvent: EventRecord; VAR itemHic: INTEGER; 
VAR handledIt: BOOLEAN; VAR doReturn: BOOLEAN); 





anEvent is the event. This method can change this value. 

itemHit is the dialog item that was hit 

handledit is not used. 

doReturn tells the Dialog Manager whether it should relinquish control to the caller 
after this event. 

Purpose This method serves as the filter procedure for a modal dialog. 

Called by the UDialog global function XFilterProc 

The default takes special actions for keystrokes, such as dealing with the Enter and 

version Return keys (maps to the default button if indicated), Tab and Shift-Tab, 


and Command-key combinations (but see remark under “DoSetupMenus’” 
about Command-key combinations in modal dialogs). 


Rarely override 








Never call 

Doldle 

PROCEDURE TDOialogqView.DoIdle(phase: IdlePhase}; OVERRIDE; 

Purpose This method is used for modeless dialogs only. It can handle idle-time 
tasks. 

The default blinks the insertion point, if necessary. 
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version a 


Originally TEvtHandler 
declared by 


Sometimes override 
Never call 





DoltemSelecied 


FUNCTION TDialogView.DoItemSelected(anItem: INTEGER; VAR handledIt: BOOLEAN; VAR 
doneWithDialog: BOOLEAN): Téommand; 





` anItem _ is the item number of the element selected by the user. 
handlediIt should be ignored. 
doneWithDialog indicates whether, as a result of this item being selected by the user, the 
dialog should be dismissed. 
The return is a command object to handle the indicated action, or gNoChanges. 
value 
ee aaaea 
Purpose š This method is called when the user clicks in a dialog item. 
Called by the UDialog global procedure StdltemHandling, 
TDialogWindow.DowninContent 
The default gives each component (TDialogitem object) a chance to “sense” the 
version message. If none does, a check is made to see whether the item continaing 


the mouse pointer is a button. If it is, DoButtonPushed is called, and if it 
returns with succeeded = TRUE, the doneWithDialog parameter of this 
method is set to TRUE. 


Rarely override You usually override DoButtonPushed instead of this method. You 
sometimes override this method if an item in the dialog activates a side 
' effect, such as in the case of a variant dialog branch. 


Never call 
ne 


DoKeyCommand 


FUNCTION TDialogView.DokeyCommand(ch: CHAR; aKeyCode: INTEGER; VAR info: EventInfo): 
TCcommand; OVERRIDE; 
nr i e e n a a U 


ch is the character whose key was pressed. 

aKeyCode _ is the code of the character ch. 

info is the event information record for the key event. 

The return is a command object that can handle the key command. 

value 

amaaa aaa 

Purpose is to handle a key press. 

The default maps the Enter and Return keys to “pushing default button”, handles Tab 

version and Shift-Tab intelligently, passes other keystrokes on to the Dialog 
Manager. 

Originally TView 
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declared by 











Rarely override 

Never call 

DoMenuCommand 

FUNCTION TDialogView.DoMenuCommand(aCmdNumber: CmdNumber): TCommand; OVERRIDE; 

The default handles the Cut, Copy, and Paste commands, including the necessary 
i desk scrap 

version conversions. 

Originally TView 

declared by 

Rarely override 

Never call 

DoSetupMenus 

PROCEDURE TDialogView.DoSetupMenus; OVERRIDE; 

The default enables the Cut, Copy, and Paste commands, as appropriate, for a 

version modeless dialog; because of some conceptual problems (see the 


implementation for details), the default version does not enable Cut, 
Copy, and Paste for a modal dialog even though the Dialog Manager 
allows the user to use Command-X, Command-C, and Command-V for 
the Cut, Copy, and Paste commands. 

Originally TView 

declared by 


Rarely. override 
Never call 


A RTL TE PTE re 


Draw : 

PROCEDURE TDialogView.Draw(area: Rect); OVERRIDE; 
A aaraa 
Purpose This method is for modeless dialogs only. 


The default tells the Dialog Manager to draw the main part of the dialog. 
version 


Originally TView 
declared by 


Rarely override 
Never call 





DrawAmendments 
PROCEDURE TDialogView.DrawAmendments (itemNumber: INTEGER); 





itemNumber is one of the dialog items in this dialog view. 
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Purpose This method draws application-defined pieces of a dialog additional to 
the basic dialog defined in the resource file. 

The default provides thick outlining for the default button. 

version 


Sometimes override 


Never cali unless you override it, in which case you can call INHERITED 
DrawAmendments so the default button will be outlined. 





IDialegView 
PROCEDURE- TDialogView.IDialogView(itsDocument: TDocument; itsStorage: Ptr; itsRsreID: 
INTEGER; itsHookItem: INTEGER; itsDfltSutton: INTEGER; isModal: BOOLEAN); 





itsDocument is the document shown in this TDialogView object. itsDocument can be 
NIL, in which case the view is documentless. 

itsStorage passes NIL for default allocation of window storage. 

itsRsrcID is the resource ID of the DLOG resource associated with this dialog 

itsHookItem is the item number of a dummy item, which you place in the list of items in 


the resource file, which serves as a hook allowing highlighting of the default 
button, to be invoked when the dialog is drawn. See the sample programs 
for examples of its use. 





itsDfltButton is the item number of a btnitm dialog item in the resource file which is to 
serve as the default button, to be pressed when Return or Enter is pressed 
by the user. 

isModal should be set to TRUE for a modal dialog, FALSE for a modeless dialog. 

The default initializes a dialog view. 

version 


Never override 











Always call this method if you create a dialog view. 

InstailKeyHandler 

PROCEDURE TDialogView, Install KeyHandler (aKeyHandler: TKeyHandler}; 

aKeyHandler is the key handler to install. 

The default installs aKeyHandler as the current key handler for the dialog and selects 
version all the characters in that key handler. 


Rarely override 
Rarely call 





MakeOwnWindow 


FUNCTION TDialogView.MakeOwnWindow(canScroll: BOOLEAN): TNialogWindow; | 


canScroll tells whether or not the dialog window should have scroll bars. 
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Purpose creates a dialog window. It is conceptually equivalent to 
NewSimpleWindow, in that it will suffice for the simplest and most wak 
cases, 

The default creates a TDialogWindow object in which the dialog view will be seen. 

version 


Sometimes override 




















Always call this method for a dialog view representing a modeless dialog. 
RetrieveText 

PROCEDURE TDialogView.RetrieveText (item: INTEGER; VAR text: Str255}; 

item is the item number in the dialog whose current text is desired. 

text is used. to return the desired text. 

The default captures the current text in the indicated dialog item and returns it in the 
version parameter text. 

Rarely override You might override this method to filter user input. 

Never cali 

SetEditSelection 

PROCEDURE TO0ialogView.SetEditSelection(editTextItem: INTEGER}; 

editTextItem identifies one of the items in the dialog. 

Purpose is to make one of the items in a dialog the selected item. 

The default installs the dialog item with the given item number, which 

version must be an EditText type of dialog item, as the current edit selection, by 


seeking the key handler defined to represent it; if none is found, a fresh kev 
handler is created automatically. 


Rarely override 











Often call 

Tab 

PROCEDURE TDlalogView.Tab(forward: BOOLEAN) ; 

forward indicates whether the selection should move to the next or the previous 
item. 

The default advances the selection to the next (forward = TRUE) or previous (forward = 

version FALSE) key handler in this dialog view’s linked list of key handlers. 


Rarely override 
Rarely call 
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TaikToUser 


PROCEDURE TDialogView.TalkToUser (VAR itemSelected: INTEGER; (PROCEDURE 
HandleSelecteditem(anItem: INTEGER; VAR done: BOOLEAN)); 





itemSelected is the item the user selected. 


HandleSelectedItem is a local procedure to handle the selected item. 





Purpose This method puts up the modal dialog and interacts with the user. This 
method doesn't return until the user dismisses the dialog box. 











Often call this method when you launch the dialog. 

Validate 

PROCEDURE TDialogView.Validate(VAR succeeded: BOOLEAN); 

succeeded tells whether or not the view was valid. 

Purpose This method interrogates all components to see if they all pass a validation 
check; if any fails, then succeeded is set to FALSE; otherwise, succeeded is 
set to TRUE. ` 

Called by TDialogView. DoButtonPushed 

The default sends a call requesting that the dialog item inspect itself to make certain 

version that all is well. Ifthe item fails a validity check , the method returns 


succeeded as FALSE. If all is well, the method returns TRUE. Typically 
only keyHandlers can fail, because they find the text that has been typed 
into them not to their liking. 


Sometimes override this method to check that all selections in the dialog are consistent. 
Rarely call 
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TKeyHandler 


MacApp Programmer’ s Guide 


Customize: sometimes 
instantiate: often 
Cali methods: often 


TKeyHandler is a TDialogltem descendant representing EditText dialog items. 
Ancestors: TObject, TEvtHandler, TView, TDialogitem 
. Fields 


rrr reat Ep yer 


fItemHandle: Handle; The actual handle to the item. This field is inherited from TDialogitem. 


fItemNumber: INTEGER; The item number in the Dialog resource file of the item. This field is 
inherited from TDialogItem 


fNextKeyHandler: TKeyHandler; Key handlers in a dialog are linked together by this mechanism 
for determining correct functioning of Tab and Shift-Tab. 


fType: INTEGER; The item type. This field is inherited from TDialogltem. 
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DoSefCursor - 
FUNCTION TkeyHandler.DoSetCursor(localPoint: Point): BOOLEAN; OVERRIDE; 














The default sets the cursor to the I-beam pointer. 

version 

Originally - TView 

declared by 

Rarely override 

Never call 

iKeyHandier 

PROCEDURE TkeyHandler.ikeyHandler(itsItemNumber: INTEGER; itsParent: TDialogView) ; 

itsItemNumber is the item number for this item. 

itsParent is the TDialogView object in which this TDialogItem object is installed. 
(TDialogView is a descendant of TCatView.) 

The default "initializes a TKeyHandler object. If itsParent is not NIL, it calls 

version itsParent.AddChild to install this view in the TDialogView object. 


Never override 











Always call this method if you create a key handler. 
InstailSelection 
PROCEDURE TkKeyHandler.InstallSelection((wasActive, beActive: BOOLEAN); OVERRIDE; 
wasActive is TRUE if the key handler is currectly active. 
beActive is TRUE if the new state is active. 
Called by TCatView.SetCurrentChild 
The default handles activation and deactivation of the insertion point. 
version 
_ Originally TDialogltem 
declared by 
Rarely override 
Never call 





itemSelected 
FUNCTION TKeyHandler.ItemSelected(anItem: INTEGER; VAR handledIt: BOOLEAN; VAR 
doneWithDialog: BOOLEAN): TCommand; OVERRIDE; 





anItem is the item number of the element selected by the user. 
handlediIt should be ignored. 
doneWithDialog indicates whether, as a result of this item being selected by the user, the 


dialog should be dismissed. 
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The return is a command object that can handle the action resulting from this 
value selection, or gNoChanges. 

Purpose is to give an item a chance to handle a mouse press in its area. 
. Called by TDialogView. DoltemSelected 

The default checks whether SELF is the same as anltem and, if it is, makes itself the 
version dialog view’s key handler and current item. If it does that, it returns 
succeeded = TRUE. 

Originally TDialogitem 

declared by r 

Rarely override 

Never call 

SelectAll 


PROCEDURE TKeyHandler.SelectAll; 
n L E a aaa a 


Purpose This method instructs the key handler to select all of its characters and 
make that the dialog’s current selection. 

Called by TDialogView. InstallKeyHandler 

The default selects all the text in an item. 

version 


Never override 
Often call 





StuffNumber 


PROCEDURE TkKeyHandler.Stuf Number (newValue: LONGINT); 
et 





newValue is the value you want to appear in the item. 

Purpose is to insert a value in a key handler. 

The default converts newValue to a character string and inserts that string as the 
version contents displayed in this item. 


Never override 
Often call 





StuffString 


PROCEDURE TKeyHandler.ScuffString(newString: Str255); 
er ae 





newString is the string you want to appear in the EdirText item. 
Purpose is to insert a string in the key handler. 

The default displays newString as the contents of the EditText item. 
version 


Never override 
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TNumberText 


Customize: rarely 
Instantiate: often 
Call methods: rarely 


TNumberText is a key handler (EditText item) that accepts only INTEGER data. 
Ancestors: TObject, TEvtHandler, TView, TDialogltem, TKeyHandler 


Fields 


he 


fCurrValue: LONGINT; The current value in the number text. 
fDigitsOnly: BOOLEAN; If TRUE, only digits (0 to 9) should be permitted as input. 
fItemHandle: Handle; The actual Handle to the item. This field is inherited from TDialogitem. 


fItemNumber: INTEGER; The item-number in the Dialog resource file of the item; 0 if none. This 
field is inherited from TDialogltem. 


£MaxDigits: INTEGER; The maximum number of digits acceptable. 
fMaxValue: INTEGER; The maximum acceptable value at validation time.. 
fMinValue: INTEGER; The minimum acceptable value at validation time. 


fNext KeyHandler: TKeyHandler; Key handlers in a dialog are linked together by this mechanism 
for determining correct functioning of Tab and Shift-Tab. This field is 
inherited from TKeyHandier. 


fType: INTEGER; The file type. This field is inherited from TDialogltem. 
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DoFilterEvent 
PROCEDURE TNumberText.DoFilterEvent (VAR anEvent: EventRecord; VAR itemHit: INTEGER; 
VAR handledIt;: BOOLEAN; VAR doReturn: BOOLEAN); OVERRIDE; 








anEvent is the current event record. 
itemHit should be ignored. 

handledit l should be ignored. 

doReturn shouid be ignored. 

The default filters out nonnumeric characters, passing everything else on. 
version l , 
Originally TDialogitem 

declared by 

Rarely override 

Never call 

INumberText 


PROCEDURE TNumberText.INumberText (itsitemNumber: INTEGER; itsParent: TDiaiogView; 
itsMinValue: INTEGER; itsMaxValue: INTEGER; itsMaxDigits: INTEGER; itsDigitsOniy: 








BOOLEAN) ; 

itsIlreemNumber is the item number for this item 

itsParent is the TDialogView object in which this TDialogitem object is installed. 

, (TDialogView is a descendant of TCatView.) 

itsMinValue is the minimum value that can be entered in this item. 

itsMaxValue is the maximum value that can be entered in this item. 

itsMaxDigits is the maximum number of digits that can be entered in this item. 

itsDigitsOnly indicates whether or not the user is allowed to enter only numbers in this 
item. CTRUE means characters other than numbers are rejected.) 

The default initializes a TNumberText object. If itsParent is not NIL, it calls 

version itsParent.AddChild to install this view in the TDialogView object. 


Never override 











Call this method if you create a TNumberText object yourself. Note that you 
usually create such an object with TDialogView.DefineNumberText, which 
calls this method for you. 

Validate 

PROCEDURE TNumberText.Validate (VAR succeeded: BOOLEAN); OVERRIDE; 

succeeded indicates whether or not the item is valid. 

Purpose is to respond when the dialog view containing this item sends a call 


requesting that the dialog item inspect itself to make certain that all is well, 
If the item fails a validity check, the method returns succeeded as FALSE. If 
all is well, the method returns succeded as TRUE. 
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Originally TDialogitem 

declared by 

Called by TDialogView. Validate 

The default checks the current characters in the item to see if they represent a valid 

version number within the constraints of [fMinValue, fMaxValuel; if not, the 
method sends an alert and returns succeeded = FALSE. If the values are 
OK, the method returns succeeded = TRUE. 

Rarely override You might override this method to put up your own alert or no alert 

Never call R 
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TRadioCluster 


Customize: never 
instantiate: often 
Call methods: rarely 


A pseudo-item representing a set of radio buttons which are to behave as a cluster of buttons, with 
one and only one selected at any moment. This type of arrangement is called a radio cluster 
because it is similar to the buttons of a car radio. 


The usual way to use this type is to define the radio buttons in your resource file and then to inform 


the dialog view in which the buttons appear that the punong are part of the same cluster, by calling 
method TDialogView.DefineRadioCluster. 


Ancestors: TObject, TEviHandler, TView, TDialogltem 





Fields 
fFirstItem: INTEGER; Item number of the first radio button in the cluster 
fLastitem: INTEGER; Item number of the last radio button in the cluster 


Note: All items between [Firsdtem and fLastltem must be radio buttons; there must be no 
discontinuity. 


fChosenItem: INTEGER; Item number of the currently chosen radio button. 
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IRadioCluster 


PROCEDURE TRadioCluster.IRadioCluster(itsItemNumber: INTEGER; itsParent: TDialogView; 
itsFirstItem: INTEGER; itsLastItem: INTEGER; itsChosenitem: INTEGER); 








itsItemNumber is the item number for. this item. 

itsParent is the TDialogView object in which this TDialogltem object is installed. 
(TDialogView is a descendant of TCatView.) 

itsFirstitem is the first item that is part of this cluster. 

itsLastItem is the last item that is part of this cluster. 

itsChosenItem is the initally chosen buton in this cluster. 

The default initializes the radio cluster. 

version 


Never override 


Rarely call You usually use TDialogView.DefineRadioCluster to create a radio cluster 
object, and that method calls this method for you. 





ltemSelected 


FUNCTION TRadicoCluster.ItemSelected{anitem: INTEGER; VAR handledIt: BOOLEAN; VAR 
doneWithDialog: BOOLEAN): TCommand; OVERRIDE; 








anItem is an item number for one of the clusters buttons. 

handledIt tells whether or not this method handled the change 

doneWithDialog tells whether or not the dialog should now be dismissed. 

Purpose is to change the selected radio button. 

Called by TDialogView. DoltemSelected 

The default unhighlights the currently selected radio button and highlights the newly 
version selected one. 

Originally TDialogitem 

declared by 


Rarely override 


Sometimes call 
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TDialogWindow 
. Customize: rarely 


instantiate: often 
Cail methods: rarely 


This is a TWindow descendant representing a DLOG resource, into which a dialog view is 
installed. 


Ancestors: TObject, TEvtHandler, TWindow 


Fields - : 
aeaea iaaa a 
fDialogView: TDialogView; The view shown in this window 
a or ee 


Important: See “TWindow” for more details on windows and their methods. 
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IDialogWindow 
PROCEDURE TDialogWindow.IDialogWindow(itsDialogView: TDialogView; itsDocument: 
TDecument; itsWmgrWindow: WindowPtr; canResize: BOOLEAN; canClose: BOOLEAN}; 


itsDialogView is the dialog view shown in this window. 

itsDocument is the document for this window. (May be NIL) l 
itsWmgrWindow is the Window Manager window controlled by this TWindow object. 
canResize tells whether or not this window has a resize box 


canClose tells whether the Close menu command should be enabled and whether 

the window has a close icon. 
a rere r a U 
The default initializes a dialog window. 
version 


Never override 


Rarely call You usually create a dialog window by using MakeOwn Window, which calls 


this method for you. 
amr rerea eaaa 
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Chapter 11 


Debugging Reference 


This chapter contains debugging reference information for MacApp. It has two sections: 


o The first section documents the debugging globals defined in UMacApp, UObject, 
UTEView, and UPrinting. (There are no debugging globals in UList) 


* The second section documents the debugging fields and methods for the object types 
defined in MacApp. Not every object type discussed in Chapter 10 is documented 
here; when one is not mentioned, it merely inherits methods and fields without 
change. 


Important: This chapter has reference information for code that is included in MacApp 
only when MacApp is compiled with debugging on. Information on using the MacApp 
debugging facilities is in Chapter 8. 


Debugging constants 
kDebugFont = monaco; The font used in the Debug window. 


kDebugSize The font size used in the Debug window. (The value is not given 
here because it is subject to change. 


Global variables 


The following are present as variables only if debugging is on when MacApp is compiled. 
If debugging is not on, there are constants with the same names, all with the value FALSE. 


gDebugPrinting: BOOLEAN; Simple toggle for debugging printing. Set when you set the Debug 
Printing debugging flag. (See “The Toggle Flag Command, X” in 
Chapter 8.) This is set by debugging code when you set the Debug 
Printing flag. 


gExperimenting: BOOLEAN; Simple toggle for enabling and disabling experimental features. 
This is set when you set the Experimenting debugging flag. (See 
“The Toggle Flag Command, X” in Chapter 8.) 


gIntenseDebugging: BOOLEAN; Toggle for intensive debugging. This is set when you set the 
Intense Debugging debugging flag. (See “The Toggle Flag 
Command, X” in Chapter 8.) 


gReportEvt: BOOLEAN; Toggle for reporting events. Set when you set the Report Events 
debugging flag. (See “The Toggle Flag Command, X” in Chapter 
8.) 


gReportMenuChoices: BOOLEAN; Toggle for tracing commands. Set when you set the Report 


Menu Commands debugging flag. (See “The Toggle Flag 
Command, X” in Chapter 8.) 
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gUnloadAliSegs: BOOLEAN; If FALSE, UnloadAllSegs does nothing. This is set when you set 
the Automatic Segment Unloading debugging flag. (See “The 
Toggle Flag Command, X” in Chapter 8.) This is TRUE when 
debugging is off. 


gDebugKeyMap: KeyMap; The key state at startup time. 


Error-handling type 


who: STRING[17]; A field added to FailInfo when MacApp is compiled with debugging 
on. See Chapter 9 for more information on FailInfo. This field 
contains name of the procedure that called CatchFailures. 


Error routines 


PROCEDURE MacsBug; INLINE $A9FF; 
Invokes MacsBug. 


PROCEDURE IDUOBJECT; 
WriteLn UObject compile date. This is called by 
TApplication IdentifySoftware. 

PROCEDURE ProgramBreak (grievance: $tr255); 
Output to the Debug window and enter debugger mode. 


PROCEDURE WritePt (pt: Point); 
Writes the given point to the Debug window. (No return is inserted after 
printing.) 

PROCEDURE WritePtr(val: UNIV LONGINT); 
Writes the hexadecimal value of the given pointer to the Debug window. 
(No Return is inserted after printing.) 

PROCEDURE WriteRect(r: Rect); 


Writes the given rectangle to the Debug window. (No return is inserted 
after printing.) 


Note: See the MacApp source code for additional utilities you can use to write debugging data.’ 


PROCEDURE ObjFail(error: INTEGER); 


This is called by MacApp when a serious error occurs and the Debug 
window is not active. It goes into an infinite loop. 
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Object debugging fields and methods 


This section documents the debugging methods and fields for the object types defined in 
MacApp. It includes one subsection for each object type discussed in Chapter 10. The 
methods and fields discussed here are present only when MacApp is compiled with 
debugging on. See Chapter 10 for complete information on these object types. 
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TObject 

TypeName 

FUNCTION TObject.TypeName: 258; 

The return is a string with eight characters (STRINGI8D. 

value 

Purpose is to return the object-type identifier. (Note this returns the identifier of the 
object’s type, not the object reference's type.) 

The defauit returns the first eight characters of the object-type identifier of the calling object. 

version 


Never override 


Sometimes call 








inspect 

PROCEDURE TObject .Inspect; 

Purpose is to provide important information about the object. 
The default writes information about the object to the Debug window. 
version 


Sometimes override When you override this method, first call INHERITED Inspect and then WriteLn 
new information about your particular type. 


Sometimes call 
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TEviHandler 


IdentifySoftware 
PROCEDURE TEvtHandler.IdentifySoftware; 


Gel UUU 


Purpose is to identify the version of the software currently running, or gives similar 
information of interest. It is used primarily for debugging. The method 
gTarget IdentifySoftware is called in response to the user choosing Show Version 
from the Debug menu. 


The default calls IdentifySoftware for the next handler in the list of handlers. 
version 


Sometimes override 
Never call 


nee 


ShowDebuginfo 

PROCEDURE TEvthandler. ShowDebugqInfo; 

Purpose is to print debugging information in the debug window. The method 
glTarget ShowDebuginfo is called when the user chooses the Show Debug Info 
command from the Debug menu. 


The default calls ShowDebuginfo for the next handler in the list of event handlers. 
version i 


Sometimes override TApplication overrides this information so that it provides extensive debugging 
information. That is usually enough. You can override this method to provide any 
information you desire. 


Never call 
Gee 
Inspect 

PROCEDURE TEvtHandler.Inspect; OVERRIDE; 

Purpose is to provide important information about the object. 

Originally 

declared by TObject 

The default prints the value of fNextHandler. 

version 


Sometimes override When you override this method, first call INHERITED Inspect and then WriteLn 
new information about your particular type. 


Sometimes call 
i i 
LookupSymbol 

FUNCTION TEvthandler.LookupSymbol (VAR sym: 288); LONGINT; 

sym is an identifier. 


The return is the value associated with the given symbol. 
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value 

T a aaa 

Purpose is to return the value associated with the given symbol. A return of —1 means that 
the symbol wasn't found, This is used by the Debugger to lookup symbols for the F 
and I commands. l ; 

The default passes the query to fNextHandler. 

version 


Sometimes override 
Never call 


eS EL 
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TApplication 


-identifySofiware 
PROCEDURE TApplication.IdentifySeftware; OVERRIDE; 


Purpose is to identify the version of the software currently running or give similar 
information of interest. It is used primarily for debugging. The method 
gTarget.IdentifySoftware is called in response to the user choosing Show Software 
Version from the Debug menu. 


The default prints the compilation date and time in the Debug window. 
version 


Sometimes override 


Never call this method unless you override it, in which case you call it as INHERITED 
IdentifySoftware 


` . j 
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TList 

Field 

fEltClass: zs8; Contains either the name of the object type of the elements of the list or the empty 
string ("). Other objects should neither read from nor write to this field. 

SetEliType 

PROCEDURE TList.SetEltType(toClass: Str255); 

toClass is the object type of the objects you intend to insert into this list. 

eR St E 

Purpose : is to set the element type for a list so an error is produced if an object of the wrong 


type is added to the list. You can call this method once and pass it the object type į 
of the objects you intend to insert into the list. The TList insert methods will then 
check the class of inserted objects and give an error if one is not of the right type. 


Never override 
Usually call this method when debugging. 
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Routine Name Index 


AboutToDraw 
AboutToDraw 
AboutToLoseControl 
Activate 
Activate 
Activate 
ActivateContents 
AdaptToScreen 
AdaptwWmgrWindow 
AddCharacter 
AddChiid 
AddDocument 
AddF reeWindow 
AddToContents 
AddToContents 
AddWindow 
AdjustExtent 
AdjustExtent 
AdjustExtent 
AdjustFeedbackFlag 
AdornPage 
AssumeFocus 

At 
AttachPrintHandler 
AutoScroll 
BanishOldText 
BanishPrintDialog 
BeInFrame 
BeInFrame 
BeInFrame ` 
BreakFollowing 
BreakFollowing 
BusyDelay 
CalcMinExtent 
CaleMinExtent 
CalcPageStrips 
CalcSBarMax 
CalcSelLoc 
CalcViewPerPage 
CalcViewPerPage 
CanOpenDocument 
CanPaste 
CantDraw 
ChangedPosition 
ChangedSize 
ChangedSize 
CheckDeskScrap 
CheckPrinter 
CheckPrinter 
ChildGrew 
ChildGrew 
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PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


TDeskScrapView.AboutToDraw 
TView. About ToDraw 
TApplication.AboutToLoseControl 
TCatView.Activate 

TView. Activate 
TWindow.Activate 

TFrame .ActivateContents 
Adapt ToScreen 

Adapt WmgrWindow 
TTETypingCommand.AddCharacter 
TCatView.AddChild 
TApplication.AddDocument 
TApplication.AddFreeWindow 
TFrame.AddToContents 
TWindow.AddToContents 
TDocument .AddWindow 
TDeskScrapView.AdjustExtent 
TTEView.AdjustExtent 
TView.AdjustExtent 
TView.AdjustFeedbackFlag 
TStdPrintHandler.AdornPage 
AssumeFocus 


FUNCTION TList.At 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


TView.AttachPrintHandler 
TFrame .AutoScroll 
TTECommand.BanishOldText 
BanishPrintDialog 
TCatView.BeInFrame 
TTEView. BeInFrame 
TView.BeInFrame 


FUNCTION TPrintHandler.BreakFollowing 
FUNCTION TStdPrintHandler.BreakFollowing 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


BusyDelay 

TTEView.CalcMinExtent 
TView.CalcMinExtent 
TStdPrintHandler.CalcPageStrips 


FUNCTION TFrame.CalcSBarMax 


PROCEDURE 
PROCEDURE 
PROCEDURE 


TTEView.CalcSelLoc 
TPrintHandler.CalcViewPerPage 
TStdPrintHandler.CalcViewPerPage 


FUNCTION TApplication.CanOpenDocument 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


CanPaste 

TView.CantDraw 

TFrame .ChangedPosition 

TFrame .ChangedSize 
TWindow.ChangedSize 
CheckDeskScrap 
TPrintHandler.CheckPrinter 
TStdPrintkHandler.CheckPrinter 
TCatView.ChildGrew 
TView.ChildGrew 
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ChooseDocument 
ChooseSpoolFile 
ClaimClipboard 
ClipFurtherTo 
Close 

Close 

Close 

Close 
CloseDocument 
CloseWindow 
CloseWindow 
CloseWmgrwWindow 
CmdToName 
CommandKey 

Commit 
CommitLastCommand 
ComputeExtent 
ComputeExtent 
ConstrainChildSize 
ContainsClipType 
ContainsClipType 
CoordToPagestrip 
CoordToPagestrip 
CountClicks 
DefineNumberText 
DefineRadioCluster 
Delete 

DeleteAll 
DeleteDocument 
DeleteFile 
DeleteFreeWindow 
DeleteWindow 
DeltactlValue 
DiskEvent 
DispatchEvent 
DisplayOnScreen 
DoBreakFollowing 
DoBreakFollowing 
DoButtonPushed 
‘DoCalcViewPerPage 
DoCalcViewPerPage 
DoCheckPrinter 
DoCheckPrinter 
DoDrawExtraFeedback 
DoDrawExt raFeedback 
DoExpand 
DoFilterEvent 
DoFilterEvent 
DoFilterEvent 
DoHandleEvent 
DoHighlightSelection 
DoHighlightSelection 
Doidle 

DoIdle 

DoIdle 
DoInGrafport 
DoInMacPrint 
DoInitialState 
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FUNCTION 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
FUNCTION 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
PROCEDURE 
PROCEDURE 
PROCEDURE 


Routine Name Index 


TApplication.ChooseDocument 
TStdPrintHandler .ChooseSpoolfile 
TApplication.ClaimClipboard 
ClipFurtherTo 
TApplication.Close 
TDocument .Close 
Tr rame.Close 
TWindow.Close 
TApplication.CloseDocument 
TApplication.CloseWindow 
TDocument .CloseWindow 
TApplication.CloseWmgrWindow 
CmdToName 

TApplication.CommandKey 
TCommand. Commit 
TApplication.CommitLastCommand 
TTEView.ComputeExtent 
TView.ComputeExtent 
TView.ConstrainChildSize 

TTEView.ContainsClipType 

TView.ContainsClipType 

TPrintHandler.CoordToPagestrip 

TStdPrintHandier.CoordToPagestrip 

TApplication.CountClicks 

TDialogView.DefineNumberText 

TDialogView.DefineRadioCluster 
TList .Delete 
TList .DeleteAll 
TApplication.DeleteDocument 


FUNCTION DeleteFile 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


TApplication.DeleteFreeWindow 
TDocument .DeleteWindow 
DeltaCtlValue 
TApplication.DiskEvent 
TApplication.DispatchEvent 
TView.DisplayOnScreen 


FUNCTION TTEView.DoBreakFollowing 
FUNCTION TView.DoBreakFollowing 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
FUNCTION 

PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


TDialogView.DoButtonPushed 
TTEView.DoCalcViewPerPage 
TView.DoCalcViewPerPage 
TCatView.DoCheckPrinter 
TView.DoCheckPrinter 
TCatView.DoDrawExtraFeedback 
TDialogView.DoDrawExtraFeedback 
TWindow.DoExpand 
TDialogitem.DoFilterEvent 
TDialogView.DoFilterEvent 
TNumberText .DoFilterEvent 
TEvtHandler.DoHandleEvent 
TCatView.DoHighlightSelection 
TView.DoHighlightSelection 
TDialogView.DoIdle 
TEvtHandler .DoIdle 
TTEView.DolIdle 

TTEView .DoInGrafport 
TStdPrintHandler.DoInMacPrint 
TDocument .DoInitialState 
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Routine Name Index 


DoIt 

DoIt 

Dolt 

DoIt 

DoIt 

Dolt 
DoItemSelected 
DoKeyCommand 
DoKeyCommand 
DoKeyCommand 
DoLocatelInterior 
DoMainFunction 
DoMakeDocument 
DoMakeEditCommand 


DoMakeTypingCommand 


DoMakeViews 
DoMakeWindows 
DoMenuCommand 
DoMenuCommand 
DoMenuCommand 
* DoMenuCommand 
DoMenuCommand 
DoMenuCommand 
DoMenuCommand 
DoMenuCommand 
DoMouseCommand 
DoMouseCommand 
DoMouseCommand 
DoMultiClick 
DoNeedDiskSpace 
` DoPagination 
DoPagination 
DoPrinterChanged 
DoPrinterChanged 
DoPrinterChanged 
DoPrintingCommand 
DoPrintingCommand 
DoRead 
DoSetCursor 
DoSetCursor 
DoSetCursor 
DoSetCursor 
DoSetInterior 
DoSetInterior 
DoSetPagedffset 
DoSetPageOffset 
DoSetupMenus 
DoSetupMenus 
DoSetupMenus 
DoSetupMenus 
DoSetupMenus 
DoSetupMenus 
DoSetupMenus 
DoSetupMenus 


DoSetupPrintingMenus 
DoSetupPrintingMenus 


DoToBreak 
DoToEvtHandler 
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TCommand.DolIt 
TPrintInBackgroundCommand.DoIt 
TPrintStyleChangeCommand.DolIt 
TTECommand .DoIit 
TTECutCopyCommand.DolIt 
TTETypingCommand.DoIt 


FUNCTION TDialogView.DoItemSelected 
FUNCTION TDialogView.DoKeyCommand 
FUNCTION TEvtHandler.DoKeyCommand 
FUNCTION TTEView.DoKeyCommand 
PROCEDURE TView.DoLocateInterior 
PROCEDURE TTECommand.DoMainFunction 
FUNCTION TApplication.DoMakeDocument 


‘FUNCTION TTEView.DoMakeEditCommand 


FUNCTION TTEView.DoMakeTypingCommand 
PROCEDURE TDocument .DoMakeViews 
PROCEDURE TDocument .DoMakeWindows 


FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
FUNCTION 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
FUNCTION 
FUNCTION 
PROCEDURE 


TApplication.DoMenuCommand 
TCatView.DoMenuCommand 
TDialogView.DoMenuCommand 
TDocument .DoMenuCommand 
TEvtHandler.DoMenuCommand 
TStdPrintHandler.DoMenuCommand 
TTEView. DoMenuCommand 
TView.DoMenuCommand 
TCat View .DoMouseCommand 
TTEView . DoMouseCommand 
TView .DoMouseCommand 
TEvtHandler .DoMultiClick 
TDocument .DoNeedDiskSpace 
TTEView.DoPagination 
TView.DoPagination 
TCatView.DoPrinterChanged 
TTEView.DoPrinterChanged 
TView.DoPrinterChanged 
TPrintHandler.DoPrintingCommand 
TStdPrintHandler.DoPrintingCommand 
TDocument .DoRead 


FUNCTION TCatView.DoSetCursor 
FUNCTION TKeyHandler.DoSetCursor 
FUNCTION TTEView.DoSetCursor 
FUNCTION TView.DoSetCursor 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


` PROCEDURE 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
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TTEView .DoSetInterior 
TView.DoSetInterior 
TTEView.DoSetPageOffset 
TView.DoSetPagedffset 
TApplication.DoSetupMenus 
TDialogView.DoSetupMenus 

TDocument .DoSetupMenus 
TEvtHandler.DoSetupMenus 
TStdPrintHandler.DoSetupMenus 
TTEView.DoSetupMenus 
TView.DoSetupMenus 
TWindow.DoSetupMenus 
TPrintHandler.DoSetupPrintingMenus 
TStdPrintuandler.DoSetupPrintingMenus 
DoToBreak 

DoToEvtHandler 
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DoTrackControl 
DoWrite 
DoneTyping 
DownInContent 
DowniInContent 
Draw 

Draw 

Draw 

Draw 

Draw 

DrawAll 
DrawAmendments 
DrawBorder i 
DrawExtraFeedback 
DrawExtraFeedback 
Drawinterior 
DrawiInterior 
DrawPageInterior 
DrawResizelIcon 
DrawView 
DumpTERecord 
Each 

EachBreak 
EachChild 
EachContainee 
EachFreeWindow 
EachHandler 
EachPage 
EmpowerChooser 
Enable 
EnableCheck 
EntDebugger 
ErrorAlert 
ExitMacApp 
FailMemError 
FailResError 
FilliInDirIbD 
FindFrame 
FindFrame 
FindobjID 
FirstContainee 
Focus 

Focus 
FocusOnBorder 
FocusOnContainer 
FocusOnContainer 
FocusOninterior 
ForAllDocumentsDo 
-ForAllViewsDo 
ForAllWindowsDo 
ForAllWindowsDo 
ForceRedraw 
ForceWMgrOnScreen 
ForceWindowOnScreen 
FrameChangedSize 
FrameChangedSize 
FrameChangedSize 
Free 


Final 


Routine Name Index 


FUNCTION TFrame.DoTrackControl 


PROCEDURE 
PROCEDURE 


TDocument .DoWrite 
TTEView.DoneTyping 


FUNCTION TDialogWindow.DownInContent 
FUNCTION TWindow.DownInContent 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
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PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


TCatView .Draw 
TDeskScrapView.Draw 
TDialogView.Draw 
TTEView.Draw 

TView.Draw 

TFrame.DrawAll 
TDialogView.DrawAmendments 
TFrame.DrawBorder 
TPrintHandler.DrawExtraFeedback 
TStdPrintHandler.DrawExtraFeedback 
TFrame .DrawInterior 
TWindow.DrawInterior 
TStdPrintHandler.DrawPageInterior 
‘TWindow.DrawResizeIcon 
TFrame .DrawView 
DumpTERecord 

TList.Each 
TStdPrintkandler.EachBreak 
TCatView.EachChild 
TFrame.EachContainee 
TApplication.EachFreeWindow 
EachHandler 
TStdPrintHandler.EachPage 
EmpowerChooser 

Enable 

EnableCheck 

EntDebugger 

ErrorAlert 

ExitMacApp 

FailMemError 

FailResError 


FUNCTION FilliInDirID 

FUNCTION TFrame.FindFrame 
FUNCTION TWindow.FindFrame 
FUNCTION FindObjID 

FUNCTION TFrame.FirstContainee 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


TFrame.Focus 

TWindow. Focus 
TStdPrintHandler.FocusOnBorder 
TFrame .FocusOnContainer 
TWindow.FocusOnContainer 
TStdPrintHandler.FocusOnInterior 
TApplication.ForAllDocumentsDo 
TDocument .ForAllViewsDo 
TApplication.ForAllWindowsDo 
TDocument .ForAllWindowsDo 
TFrame .ForceRedraw 
ForceWMgroOnScreen 
ForceWindowOnScreen 
TCatView.FrameChangedSize 
TTEView, FrameChangedSize 
TView,.FrameChangedSize 

Free 
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Routine Name Index 


Free 

Free 

Free 

Free 

Free 

Free 

Free 

Free 

Free 

Free 

Free 

Free 

Free 

Free 

FreeData 
FreeFile 
FreeFromClipboard 
FreeFromClipboard 
FullScreenSize 
GetBreakCoord 
GetDataToPaste 
GetEvent. 
GetFocus 
GetMoveBounds 
GetMoveBounds 
GetResMenu 
GetResizeLimits 
GetResizeLimits 
GetRsrcWindow 
GetSavelInfo 

Get TempName 
GetViewedRect 
GetViewedRect 
GetWindowPos 
GivePasteData 
GivePasteData 
RandleAlienEvent 
HandleFinderRequest 
HandleSelecteditem 
HandlerReturned 
HaveView 
TApplication 
ICatView 
ICommand 
IDUTrace 
IDeskScrapView 
IDialogItem 
IDialogqView 
IDialogWindow 
IDocument 
IEvtHandler 
IFrame 
IKeyHandler 
IList i 
INumberText 
IPrintHandler 


IPrintInBackgroundCommand 
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PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
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PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
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TCatView.Free 

TDialogView.Free 
TDialogWindow.Free 

TDocument .Free 
TEvtHandler. Free 

TFrame.Free 
TPrintInBackgroundCommand.Free 
TPrintStyleChangeCommand.Free 
TStdPrintHandler. free 
TTECommand.Free 
TTECutCopyCommand. Free 
TTETypingCommand.Free 

TView. Free 

TWindow.Free 

TDocument .FreeData 
TDocument.FreeFile 

TDocument .FreeFromClipboard 
TView.FreeFromClipboard 
TWindow.FullScreenSize 
TStdPrintHandler.GetBreakCoord 


FUNCTION TApplication.GetDataToPaste 
FUNCTION TApplication.GetEvent 


PROCEDURE 
PROCEDURE 
PROCEDURE 


GetFocus 
Trrame.GetMoveBounds 
TWindow.GetMoveBounds 


FUNCTION GetResMenu 
PROCEDURE TFrame.GetResizeLimits 
PROCEDURE TWindow.GetResizeLimits 


FUNCTION TApplication.GetRsrcWindow 
FUNCTION TDocument .GetSaveiInto 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


TDocument .Get TempName 
TFrame.GetViewedRect 
TStdPrintHandler.GetViewedRect 
GetWindowPos 


FUNCTION TTEView.GivePasteData 
FUNCTION TView.GivePasteData 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


TPrint InBackgroundCommand. IPrint InBackgroundComma: 


TApplication.HandleAlienEvent 
TApplication.HandleFinderRequest 
HandleSelectedItem 
HandlerReturned 
TFrame.HaveView 
TApplication.IApplication 
TCatView, ICatView 

TCommand. ICommand 

IDUTrace 

TDeskScrapView. IDeskScrapView 
TDialogitem.IDialogItem 
TDialogView. IDialogView 
TDialogWindow.IDialogWindow 
TDocument .IDocument 
TEvtHandler.IEvtHandler 
TFrame. IFrame 
TKeyHandler.IKeyHandler 
TList.IList 
TNumberText.INumberText 
TPrintHandler.IPrintHandler 
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IPrintStyleChangeCommand 


TRadioCluster 
LStdPrintHandler 
ITECommand 
ITECutCopyCommand 
ITEPasteCommand 
ITETypingCommand 
ITEView 

IView 

IWindow 

IdUobject 
IdentifySoftware 
IdentifySoftware 
IdentifySoftware 
IdentifySoftware 
IdentifySoftware 
Idle 

InitPrinting 
InituDialog 
InsertFirst 
InsertLast 

Inspect 

Inspect 

Inspect 

Inspect 

Inspect 

Inspect 

Inspect 

Inspect 

Inspect 

Inspect 
InspectObject 
InstallCohandler 
InstallKeyHandler 
InstallNewText 
InstallSelection 
InstallSelection 
InstallSelection 
InvalAllPageFeedback 
InvalAllPageFeedback 
InvalAssumingFocused 
InvalAssumingFocused 
InvalDonut 
InvalidRect 
InvalidRect 
ItemSelected 
ItemSelected 
ItemSelected 
KindOfDocument 
LastCommandWas 
LaunchClipboard 
LocatePageInterior 
LocatePageInterior 
LookupErrString 
LookupObjName 
LookupSymbol 
LookupSymbol 


Final 


PROCEDURE 


TPrintStyleChangeCommand.IPrintStyleChangeCommand 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


PROCEDURE . 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


Routine Name Index 


TRadioCluster.IRadioCluster 
TStdPrintHandler.IStdPrintHandler 
TTECommand. ITECommand 
TTECutCopyCommand. ITECutCopyCommand 
TTEPasteCommand. ITEPasteCommand 
TTETypingCommand. ITETypingCommand 
TTEView. ITEView 

TView.IView 

TWindow. IWindow 

IdUobject 
TApplication.IdentifySoftware 
TEvtHandler.IdentifySoftware 
TStdPrintHandler.IdentifySoftware 
TTEView.IdentifySoftware 

TView .IdentifySoftware 
TApplication.Idle 

InitPrinting 

InitUDialog 

TList.InsertFirst 
TList.InsertLast 

Inspect 

TApplication.Inspect 

TCommand. Inspect 

TDeskScrapView. Inspect 
TDocument . Inspect 
TEvtHandler.Inspect 

TFrame. Inspect 

TList. Inspect 

TView. Inspect 

TWindow. Inspect 

InspectObject 
TApplication.InstallCohandler 
TDialogView.InstallKeyHandler 
TTECommand.InstallNewText 
TEvtHandler.InstallSelection 
TKeyHandiler.InstallSelection 
TTEView.installSelection 
TPrintHandler, InvalAllPageFeedback 


TStdPrintHandler. InvalAllPageFeedback 


TFrrame.InvalAssumingFocused 
TView.InvalAssumingFocused 
InvalDonut 
TFrame.InvalidRect 
TView.InvalidRect 


FUNCTION TDialogItem.ItemSelected 
FUNCTION TKeyHandler.ItemSelected 
FUNCTION TRadioCluster.ttemSelected 
FUNCTION TApplication.KindOfDocument 
FUNCTION LastCommandWas 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


TApplication.LaunchClipboard 
TPrintHandler.LocatePageinterior 
TStdPrintHandler.LocatePageInterior 
LookupErrString 
LookupOb jName 


FUNCTION LookupSymbol 
FUNCTION TEvtHandler.LookupSymbol' 
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MainEventLoop PROCEDURE TApplication.MainEventLoop 
MakeNewCopy PROCEDURE TDocument .MakeNewCopy 
MakeOwnWindow FUNCTION TDialogView.MakeOwnWindow 
MakeTERecord PROCEDURE TTEView.MakeTERecord 

MenuEvent FUNCTION TApplication.MenuEvent 

Move PROCEDURE TFrame.Move 

Move PROCEDURE TWindow.Move 

MoveByUser PROCEDURE TWindow.MoveByUser 
MovedContainer PROCEDURE TFrame.MovedContainer 
NewPaletteWindow _ FUNCTION NewPaletteWindow 

NewS impleWindow FUNCTION NewSimpleWindow 

NilPatch PROCEDURE NilPatch 

NilPatch PROCEDURE NilPatch' 

Not Yet Implemented PROCEDURE NotYet Implemented 

NowFocused PROCEDURE NowFocused 

OBJFail PROCEDURE OBJFail 

ObeyEvent PROCEDURE TApplication.ObeyEvent 
OneSubJob FUNCTION TStdPrintHandler.oOneSubJob 

Open - PROCEDURE TFrame.Open 

Open PROCEDURE TWindow.Open 

OpenFile PROCEDURE OpenFile 

OpenNew PROCEDURE TApplication.OpenNew 

Opendld PROCEDURE TApplication.Opendold 
OpenWindow PROCEDURE TApplication.OpenWindow 
OpenWindow PROCEDURE TDocument .OpenWindow 
PageInteriorChanged PROCEDURE TTEView.PageInteriorChanged 
PageInteriorChanged PROCEDURE TView.PageInteriorChanged 
ParseTitleTemplate FUNCTION ParseTitleTemplate 

PatchTrap FUNCTION PatchTrap 

PatchTrap FUNCTION PatchTrap 

PerformCommand PROCEDURE TApplication.PerformCommand 
PerformPrinting FUNCTION TStdPrintHandler.PerformPrinting 
PollEvent PROCEDURE TApplication.PollEvent 
PoseJobDialog PROCEDURE TStdPrintHandler.PoseJobDialog 
PosePageSetupDialog FUNCTION TStdPrintHandler.PosePageSetupDialog 
PosePrintDialog PROCEDURE TStdPrintHandler.PosePrintDialog 
PrepareForDialog PROCEDURE PrepareForDialog 

Print FUNCTION TDocument.Print 

Print FUNCTION TPrintHandler.Print 

Print FUNCTION TStdPrintHandler.Print 
PrintDocument FUNCTION TApplication.PrintDocument 
PrintPage PROCEDURE TStdPrintHandler.PrintPage 
PrintSpoolFile PROCEDURE PrintSpoolFile 

PrinterChanged PROCEDURE TPrintHandler.PrinterChanged 
PrinterChanged PROCEDURE TStdPrintHandler.PrinterChanged 
PutDeskScrapData FUNCTION PutDeskScrapData 

ReadFromFile PROCEDURE TDocument .ReadFromFile 
RecalcText PROCEDURE TTEView.RecalcText 
RectIsVisible FUNCTION RectIsVisible 

RectsNest FUNCTION RectsNest 

RedoIt PROCEDURE TCommand.RedoIt 

RedoIt PROCEDURE TPrintStyleChangeCommand.RedoIt 
RedoIt PROCEDURE TTECommand.RedoIt 
RedoPageBreaks PROCEDURE TPrintHandler.RedoPageBreaks 
RedoPageBreaks PROCEDURE TStdPrintHandler.RedoPageBreaks 
Reduce “PROCEDURE Reduce 

RemoveAdditions PROCEDURE TTECommand.RemoveAdditions 
RemoveDeletions PROCEDURE TList.RemoveDeletions 

Final page Appendix 7 





MacApp Programmer's Guide 


ReportEvent 
ReportMouseDown 
ResetBusyCursor 
Resize 
ResizeByUser 
ResizedContainer 
RestoreSelection 
RetrieveText 
RevealRect 
Revert 
ReviveDeletions 
ReviveDeletions 
Run 

SFGetParms 

Save 
SaveInPlace . 
SaveViaTemp 
Savedon 
ScaleDist 
ScalePoint 
ScaleRect 
ScrilToSBars 
ScrollBy 
ScrollSelectionIntoView 
ScrollStep 
SelectAll 
SetCmdName 
SetCurrentChild 
SetDfitPrintinfo 
SetEditSelection 
SetEltType 
SetExtent 
SetExtent 
Setfocus 
SetHLPenState 
SetMargins 
SetMenuState 
SetPage 
SetPageInterior 
SetPagedffiset 
SetPageOffset 
SetSBarMax 
SetStdFont 
SetStyle 
SetTitle 
SetTitleForDoc 
SetTransformer 
SetUndoText 
SetVisibility 
SetupTheMenus 
ShallowFree 
ShowDebuginfo 
ShowDebuginfo 
ShowDebugInfo 
ShowDebugInfo 
ShowDocBeingPrinted 
ShowError 
ShowMet rics 


Final 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


Routine Name Index 


ReportEvent 

ReportMouseDown 
ResetBusyCursor 

TFrame .Resize 
TWindow.ResizeByUser 
TFrame.ResizedContainer 
TTECommand.RestoreSelection 
TDialogView.RetrieveText 
TFrame.RevealRect 

TDocument .Revert 
TTECommand.ReviveDeletions 
TTECutCopyCommand.Revivebeletions 
TApplication.Run 
TApplication.SFGetParms 
TDocument .Save 

TDocument .SaveInPlace 
TDocument .SaveViaTemp 
TDocument .SavedOn 

ScaleDist 

ScalePoint 

ScaleRect 
TFrame.ScritoSBars 
TFrame.ScrollBy 
TTEView.ScrollSelectianintoview 


FUNCTION TFrame.ScrollStep 


. PROCEDURE 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCERURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


TKeyHandler.SelectAll 
SetCmdName : 
TCatView.SetCurrentChild 
TStdPrintHandler.SetDfltPrintiInfo 
TDialogView.SetEditSelection 
TList .SetEltType 
TTEView.SetExtent 
TView.SetExtent 

SetFocus 

SetHLPenState i 
TStdPrintHandler.SetMargins 
SetMenuState 
TStdPrintHandler.SetPage 
TStdPrintHandler.SetPageInterior 
TPrintHandler.SetPageOffset 
TStdPrintHandler.SetPageOffset 
TFrame .SetSBarMax 

SetStdfont 

SetStyle 

TDocument .SetTitle 
TWindow.SetTitleForDoc 
SetTransformer 
TApplication.SetUndoText 
TDialogiItem.SetVisibility 
TApplication.SetupTheMenus 
ShallowFree 
TEvtHandler.ShowDebuginfo 
TStdPrintHandler.ShowDebuginfo 
TTEView. ShowDebuginfo 
TView.ShowDebuginfo 
TStdPrintHandler.ShowDocBeingPrinted 
TApplication.ShowError 
TStdPrintHandler.ShowMetrics 
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ShowReverted 
ShowReverted 
ShowSBars 
ShowWindows 
SimpleStagger 
StaggerWmgrWindow 
StdAlert 
StditemHandling 
StopPrinting 
StopPrinting 
StuffNumber 
StuftString 
StuffTERects 
SubstituteCaptureProcs 
SwitcherEvent 
TRCBreak 
TRCEnable 
TRCException 
TRCFLlag 
TRCGetProcName 
TRCGlohalHandle 
TRCLInt ToHex 
TRCOb TypeName 
TRCTerminate 
Tab ` 

TailPatch 
TailPatch 
TalkToUser 
TempName 
Terminate 
Terminate 
TestFrame 
ToggleState 
TrackAppControl 
TrackConstrain 
TrackCursor 
TrackFeedback 
TrackInContent 
TrackMouse 
TransterTheControl 
UndolIt 

UndoIt 

UndoIt 
UnpatchTrap 
UnpatchTrap 
UpdateEvent 
UpdateEvent 
Validate 
Validate 
Validate 
ValidatePrintRecord 
ViewResized 
WWAddText 
WWEndForce 
WWEorceOutput 
WWGrown 
WWinvalGrowBox 
WWNew 
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PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
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TDocument .ShowReverted 
TView. ShowReverted 
TFrame .ShowSBars 
TDocumernit .ShowWindows 
SimpleStagger 
StaggerWmgrWindow 
StdAlert 
StdItemHandling 


TPrintHandler.StopPrinting 
TStdPrintHandler.StopPrinting 


TKeyHandler.StuffNumber 
TKeyHandler. StuffString 
TTEView.StuffTERects 


TStdPrintHandler.SubstituteCaptu 
TApplication.SwitcherEvent 


TRCBreak 
TRCEnable 
TRCException 
TRCFlag 
TRCGetProcName 
TRCGlobalHandle 
TRCLIntToHex 
TRCOb} TypeName 
TRCTerminate 
TDialogView.Tab 


FUNCTION TailPatch 
FUNCTION TailPatch 


PROCEDURE 
PROCEDURE 
PROCEDURE 


PROCEDURE TStdPrintHandler. Terminate 


TDialogView.TalkToUser 
TempName 
TEvtHandler.Terminate 


FUNCTION TestFrame 


PROCEDURE 


ToggleState 


FUNCTION TFrame.TrackAppControl 


PROCEDURE 


PROCEDURE TApplication.TrackCursor 


PROCEDURE 


TCommand.TrackConstrain 


TCommand.TrackFeedback 


FUNCTION TFrame.TrackInContent 
FUNCTION TCommand.TrackMouse 


PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 
PROCEDURE 


TransferTheControl 
TCommand.UndoIt 


TPrintStyleChangeCommand.UndoIt 


TTECommand.UndoIt 
UnpatchTrap 
UnpatchTrap 
TFrame.UpdateEvent 
TWindow.UpdateEvent 
TDialogitem.Validate 
TDialogView.Validate 
TNumberText .Validate 


reProcs 


TStdPrintHandler.ValidatePrintRecora 


TFrame.ViewResized 
WWAddText 
WWEndForce 
WWForceOutput 
WWGrown 
WWinvalGrowBox 
WWNew 
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WwWReadLa FUNCTION WWReadin 

WWRedirect FUNCTION WWRedirect 

WouldPrintRect FUNCTION TPrintHandler.WouldPrintRect 
WouldPrintRect FUNCTION TStdPrintHandler.WouldPrintRect 
WouldtTakeClick FUNCTION TView.WouldTakeClick 
WrLblBoolean PROCEDURE WrLblBoolean 

WrLblPtr PROCEDURE WrLblPtr 

WrLblRect PROCEDURE WriLblRect 

WriteToDeskScrap -> PROCEDURE TTEView.WriteToDeskScrap 
WriteToDeskScrap PROCEDURE TView.WriteToDeskScrap 
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MacApp 1.0B2 Release 


Important — Required Versions of the Macintosh Programmer’s Workshop 


To use this release you must have installed release 1.0B2 of the Macintosh Programmer's Workshop (MPW). 
MacApp 1.0B2 will not work with earlier releases due to bugs and differences in the Pascal compiler and libraries. 


Release Contents 


This release consists of four 400K diskettes. For details, see the document “MacApp Release Disks” and 
the MacApp Reference Manual. 


The release contains: 

The file *Macapp Info, which contains much of the information in this document as well as some handy 
commands for building the sample programs. 

The MPW tool PostRez, used to postprocess resource files. 

The MPW tool Optimize, used to optimize object-oriented code. 

The files MacAppStartup and MacAppStartup.XL, used to set up the MPW environment for MacApp. 
The file Build, used to build MacApp applications. 

The foider MacApp Make Files, which contains the files used for building MacApp, as well as a tempiate 
for an application's make file named Application.make. 

The foider MacApp Source Files, which contains ali the source for MacApp itself (both Pascal and 
assembly language). This consists of the modules Object (basic Object Pascal Support), List 
(support for lists of objects), MacApp (main part of MacApp), Printing (for applications that print), 
Dialog (for modal and modeless dialogs and concatenated views), TEView (a cover for TextEdit), 
and Trace and WriteinWindow (only used for debugging). 

+ The folder MacApp Resource Files, which contains all the Rez files which define common MacApp 
resources, 

The folder MacApp Samples, which contains the sample programs. 

* The folder Manual Samples, which contains the examples from Chapter 1 and Chapter 6 of the MacApp 
Reference Manual and MPW Shell scripts to build them. 

The folder MacApp Object Files, which contains the WriteinWindow driver (wwDriver.c.o) and which is 
where compiled MacApp code is stored. 


eo è s s s e 


. 


This package includes a list of the documentation that you shouid have received. Consult this list to ensure 
that you received all the documentation. 


installation 


Create a folder named MacApp in your MPW folder (or elsewhere, if you prefer). Copy the contents of all four 
disks into your MacApp folder. Drag the contents of any folders whose names are of the form More x (or Sti! 
More x) into the corresponding foider x; discard the More x folders. Modify your UserStartUp file in the MPW 
folder to contain the lines: 


Set MacApp "{MPW)}MacApp" 
Export MacApp 
execute "{MacApp}MacAppStartup" 


It you've placed the MacApp folder elsewhere, specify the appropriate folder in the first line. If you are using 
an MFS hard disk (such as one attached to a Macintosh XL), insert the following lines instead: 


Set MacApp “{MPW}" 


Export MacApp 
execute "{MacApp}MacAppStartup.XL" 
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If you are low on disk space, there are a couple of things you can do: 


* Delete any fonts, desk accessories, print drivers, utilities, etc. which you don't need. 
e Don't copy the sources to all the MacApp example programs onto your disk. 


When the installation is done, you should be abie to build one of the sample programs, or better yet, one of 
your own MacApp programs. Refer to the MacApp reference manual or the file ““MacApp Info” for details on 
how to build a program. x 


Notes for Users of Previous Releases 


Functional changes have been made; read the document “MacApp Change History” to leam how to change 
your application. 


Reporting Bugs, Comments, and Suggestions 


As of this release, the MacApp interface is frozen. No further changes will be made that will affect your 
programs (uniess you have unusual overrides). However, please feel free to continue sending in suggestions, 
complaints, comments, ideas, and so on; they may be incorporated into a future release. You should also 
report places where the documentation was not clear enough or just plain wrong. 


We are also interested in hearing about any bugs that you find in MacApp. When you report a bug, try to be 
as specific as possible, and include pieces of code, if appropriate. Also, don't hesitate to contact us if you are 
having difficulties with MacApp; by finding out what things people have trouble with, we know what features 
need better comments and documentation. 


if you are a registered or certified developer, you should use your usual channels for reporting bugs, 
comments, and suggestions. If you have access to CSNET or USENET, then you can contact us by electronic 
mail. if you send mail to macapp@Apple (CSNET) or apple !macapp (USENET), you will reach one of the 
MacApp team. We have also setup a mailing list of ali the MacApp users that we know about, which is 
Info-MacApp@Apple (apple! Info-MacApp). Mail sent to Info-MacApp will be forwarded to MacApp users 
with network access. If you have a bug report or comment that would be of interest to all MacApp users, send it 
tO Info-MacApp rather than macapp. If you want to be added or removed from the Info-MacApp list, send 
mail to Info-MacApp-Request Apple. : 


Known Bugs 
We hope to fix all of these for the next release: 


+ The Pascal compiler occasionally overflows its stack. If this happens, increase the MPW stack as described 
in the MPW 1.082 release notes. This will be fixed in the next release of MPW. 

e The bug fix for Beep crashing on a Mac XL disappeared somehow in MPW 1.0B2. If you are using an XL, 
edit MacAppStartup.XL to replace the Beep commands with something eise. 

e The TEView unit is too slow. Also, Undo Typing doesn't work and TTETypingCommand does not handle 
the first keystroke properly. 

+ Error messages from UPrinting are non-standard and incomplete. 

* Documents which swap views in one frame (such as Flow and Cards) do not free the view which is not 

currently showing when the document is closed. 

Error checking in UList is incomplete, and most users of TList do not consider failures in methods that 

could in fact fail (such as TList.InsertFirst or .InsertLast). 

It is frequently not possible to exit back to MPW or the Finder if you've crashed into the MacApp debugger. 

gTarget sometimes seems to be improperly set to gApplication when a document window is open. Let us 

know if you can reproduce this. 

° MacApp has troubie recovering if you try to save a file on top of another one which is currently open. 
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MacApp Release Disks 
(version 1.0B2) 


This document briefly describes each of the files that comes with the MacApp release (version 1.082). For 
more details on many of these files, refer to other documents in the package. à 


Folder MacApp 


*macApp info 
Contains useful build commands and instructions for installing MacApp, as well as last-minute 
information. 
Build 
The MPW Shell script that you run to rebuild an application; e.g., in the Shell, type: 
Build App. You must also have a .make file for your application. 
MacAppStartup 
Shell script called from UserStartup, which sets up environment variables for MacApp 
MacAppStartup.XL 
Like MacAppStartup, but for use on MFS (flat directory) disks. 
Optimize P 
An MPW tool, run by the make file when you Say Build App opt, which optimizes calls to object 
methods. 
PestRez 
An MPW tool run by the make file, which converts emnu resources into MENU resources and builds the 
mntb 0 resource. 


Folder MacApp Make Files 


Application.make 
A prototype .make file for an application. Look at this one and the sample programs to learn how to make 
your own. 

MacApp.make 
Used to build the MacApp library by Saying Build MacApp. This is optional; the normal build procedure 
will build the library, if necessary. 

MacApp.makel, MacApp.make2, MacApp.opt.make2, MacApp.make3 
The make files that the Build script combines with your application’s make file to build your program. 
Read these if you want to learn more about how Make files work. 

MacAppDebugState 
Marker file used by the build process to determine whether the MacApp library and your program were last 
compiled with or without debugging. 


Folder MacApp Source Files 


UDialog.p, UDialog.incl.p 
Contains the Pascal unit UDialog. UDialog implements a few useful services including: clusters of radio 
buttons, a default button, and reading numeric text fields. It also defines the TCat View (concatenated 
yiew) class, which allows you to place views within views. 
UList.p, UList.inci.p 
Source for UList. 
UVObject.a, CommonObjLib.a, UObject.p, UObject.incl.p, Objlib.incl.p 
Source code for low-level object Pascal support. 
UPatch.a 
Implementation of a couple of procedures for patching Toolbox traps. 
UPatch.p 
Pascal unit that defines the interface to the routines in UPatch.a; contains no code. 
UMacApp.a 
Assembly source for MacApp. 
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UMacApp.p, UMacApp.inci.p,. UMacApp.ince2.p, UMacApp.inc3.p 
Interface definitions and implementation for the main part of MacApp. 
UPrinting.p, UPrinting.inci.p 
Pascal unit which contains the printing code. Use this if your applications prints. 
UTEView.p, UTEView.incl.p 
Pascal unit which defines TTEView object type, which is a cover for TextEdit. 
UTrace.p, UTrace.inci.p ' 
Contains the MacApp debugger. Only needed when debugging. 
UWritelnWindow.p, UWritelnWindow.incl.p 
Contains code to implement the Debug (Writeln) window. Only needed when debugging. 


Folder MacApp Resource Files 


MacApp.r 
` Rez input file for MacApp common resources 

Debug.r 

Rez input file for debugging resources. 
Dialog.r 

Rez input file for programs that use UDialog. 
Printing.r 

Rez input file for printing resources. 


MacAppTypes.r 
The Rez template definition file for MacApp (contains the definition for type cmnu). 


This folder also contains the compiled resource files for MacApp, once built. 


Folder MacApp Object Files 


wwDriver.c.o 
Object code for WritelnWindow driver. 
This folder also contains the object code for MacApp, once built. 


Folder MacApp Samples 


Contains eleven folders named “{program} Sample’, each containing: 
Miprogram}.p 
{program}.r 
{program} .make 
` O{program}.p 
U{program}.inci.p 


Main program, Rez file; Make file, Unit interface, and Unit implementation for the sample program 
{sample}. For a complete description of the sample programs, see the MacApp Reference manual. In 
addition, the folder Flow Sample includes FlowExtras.rsrc, UFlowChart.p, and UFlowChart.inct.p. The 
folder Conference Sample includes UAppleTalk.p, UAppleTalk.inc1.p, and AppleTalk. RSRC. 


Folder Manual Samples 


Contains the examples from the introductory and Object-Oriented Assembler chapters of the manual. 
MPasExample.p, BuildPasExample 

Conventional Pascal example program and a shell script to build it. 
MObjPasExample.p, UObjPasExample.p, BuildObjPasExample 

Object Pascal example main program, unit, and a shell script to build it. 
MObjPas2Example.p, BuildObjPas2Example 

Modified Object Pascal example main program and a shell script to built it. 
ObjAsmExample.a, BuildObjAsmExample 

Object Assembler example program and a shell script to build it. 
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Contents of Release Diskettes 


Name Type Crtr 


:MacApp 1.0B2 (1): 
*Macapp Info TEXT 
Build TEXT 


MPS 
MPS 


MacApp Make Files Folder 
MacApp Object Files Folder 
MacApp Resource Fil. Folder 
MacApp Source Files Folder 


MacAppStartUp TEXT MPS 
MacAppStartUp.xL TEXT MPS 
Manual Samples Folder 

Optimize MPST MPS 
PostRez g MPST MPS 
:MacApp 1.082 (1):MacApp Make 
Application.make TEXT MPS 
MacApp.make TEXT MPS 
MacApp.makel TEXT MPS 
MacApp.make2 TEXT MPS 
MacApp.make3 TEXT MPS 
MacApp.opt .make2 TEXT MPS 
MacAppDebugState TEXT MPS 


Last~Mod-Date 


Creaticn-Date 


15K 


19K 
214K 


36K 
46K 
13K 


Files: 
3K 
2K 
3K 
2K 
3K 
2K 
1K 


lvbspocid 
lvbspociIad 
lyvbspocid 
lvbspocid 
lvbspocid 
livbspocid 
ilvbspocid 
ivbspocid 
ivbspocid 
livbspocid 
ivbspociId 


ivbspocid 
lvbspocld 
lvpspocId 
lvbspocld 
lvbspociId 
lvbspociId 
lvbspocId 


:MacApp 1.0B2 {(1):MacApp Object Files: 


wwDriver.c.o OBJ 


MPS 


1K 


ivbspociId 


:Macāpp 1.0B2 (1) :MacApp Resource Files: 


Debug.r TEXT 
Dialog.r TEXT 
MacApp.r TEXT 
MacAppTypes.r TEXT 


Printing.r TEXT 


MPS 
MPS 
MPS 
MPS 
MPS 


2K 
2K 
8K 
2K 
6K 


lvbspocīd 
ivbspocid 
lvbspocId 
lvbspocid 
lvbspoclId 


sMacApp 1.0B2 (1):MacApp Source Files: 


CommonObjLlib.a TEXT 
Objlib.inel.p TEXT 
UDialog.inci.p TEXT 
UDialog.p TEXT 
UList.incl.p TEXT 
UList.p TEXT 
UMacApp.a TEXT 
UMacApp.incl.p TEXT 
UMacApp.inc2.p TEXT 


MPS 
MPS 
MPS 
MPS 
MPS 
MPS 
MPS 
MPS 
MPS 


11K 
6K 
32K 
21K 
9K 
6K 
5K 
78K 
47K 


:MacApp 1.0B2 {1):Manual Samples: 


BuildOb jAsmExample TEXT 
BuildObjPas2ZExample TEXT 


BuildObjPasExample TEXT 
BuildPasExample TEXT 
MOb j}Pas2Example.p TEXT 
MOb jPasExample.p TEXT 
MPasExample.p TEXT 
ObjAsmExample.a TEXT 
UObjPasExample.p TEXT 
UPasExample.p TEXT 
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MPS 
MPS 
MPS 
MPS 
MPS 
MPS 
MPS 


1K 
1K 
1K 
1K 
2K 
2K 
2K 
18K 
6K 
4k 


lvbspocid 
lvpspocId 
lvbspocId 
livbspociId 
lvbspocid 
lvbspocid 
ivbspocid 
lvbspociId 
lvbspocid 


lvbspociId 
lvbspocid 
lvbspocid 
ivbspocid 
lvbspocld 
lvbspocid 
ivbspocid 
livbspociId 
lvbspoclid 
lvbspocid 


8/1/86 
8/1/86 
8/6/86 
8/6/86 
8/6/86 
8/6/86 
7/25/86 
7/25/86 
8/6/86 
7/24/86 
7/28/86 


7/18/86 
7/17/86 
8/1/86 
7/29/86 
8/1/86 
7/29/86 
7/1/86 


7/25/86 


7/18/86 
7/18/86 
7/18/86 
7/17/86 
7/24/86 


“7/21/86 


7/21/86 
7/28/86 
7/28/86 
7/31/86 
7/21/86 
7/28/86 
7/28/86 
7/31/86 


8/5/86 
8/5/86 
8/5/86 
8/5/86 
6/24/86 
6/24/86 
6/3/86 
7/18/86 
6/24/86 
6/3/86 


5:26 
5:26 
5:24 
12:13 
11:20 


3:55 
6:05 
12:27 
12:28 
10:16 
3s I7 
2:35 
3:09 
11:10 


6:07 
5:54 
5:54 
§:55 
5:14 
5:15 
10:29 
4:54 
5:14 
10:43 


2/19/86 


6/27/86 
7/1/86 
6/2/86 
6/2/86 

7/28/86 

5/20/86 

5/20/86 
7/1/86 

7/24/86 

7/28/86 


7/1/86 
4/27/50 
6/26/86 
6/26/86 
6/27/86 
6/27/86 
6/27/86 


7/25/86 


a 


7/17/86 
7/17/86 
7/17/86 
5/16/86 
7/17/86 


7/3/86 
7/3/86 
7/3/86 
7/3/86 
7/3/86 
7/3/86 
7/3/86 
7/3/86 
7/3/86 


6/9/86 
6/3/86 
6/3/86 
6/3/86 
6/3/86 
5/26/86 
6/3/86 
5/27/86 
5/25/86 
6/3/86 


11:00 
10:13 
3:00 
§:03 
5:03 
5:57 
5:31 
5:31 
3:04 
6:02 
6:23 


L337 
8:43 
5:19 
5:20 
2:01 
1:27 

10:14 


4:09 
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iMacApp 1.0B2 (2): 
More MacApp Source . Folder 375K 


sMacApp 1.0B2 (2):More MacApp Source 


UMacApp.inc3.p TEXT MPS 62K 
UMacApp.p TEXT MPS 99K 
uObject.a TEXT MPS 12K 
Udbject.incl.p TEXT MPS 12K 
Uobject .p TEXT MPS TK 
Upatch.a TEXT MPS 5K 
UPatch.p TEXT MPS 2K 
UPrinting.inci.p TEXT MPS 64K 
UPrinting.p TEXT MPS 23K 
UTEView.incl.p TEXT MPS 34K 
UTEView.p TEXT MPS 14K 
UTrace. incl. p TEXT MPS 42K 
UTrace.p TEXT MPS 3K 


ene Ree eee eee Ree me am 


:MacApp 1.0B2 (3): 
MacApp Samples Folder 310K 
Still More MacApp S.. Folder 23K 


:MacApp 1.0B2 (3):MacApp Samples: 


Cards Sample Folder 57K 
Conference Sampie Folder 132K 
DemoDialogs Sample Folder 22K 
DemoText Sample Folder 28K 
DrawShapes Sample Folder 72K 


lvbspocid 


Files: 

lvbspocid 
ivbspocid 
lvbspoclId 
lvbspocid 
ivbspoclid 
ivbspocia 
ivbspoclId 
lvbspocld 
lvbspocid 
lvbspociId 
ivbspocid 
lvbspoclId 
lvbspocid 


lvbspocid 
lvbspocid 


lvbspociId 
lvbspociId 
lvpspocid 
lvbspocid 
ivbspocld 


t:MacApp 1.0B2 (3):MacApp Samples:Cards Sample: 


Cards ,make TEXT MPS 2K 
Cards.r TEXT MPS 5K 
MCards.p TEXT MPS 1K 
UCcards.incl.p TEXT MPS 31K 
UCards.p TEXT MPS 18K 


ivbspocid 
lvpspoclId 
lvbspocid 
ivbspociId 
lvbspocid 


8/6/86 


8/1/86 1 
7/28/86 
7/21/86 
7/31/86 
7/25/86 
7/21/86 

7/3/86 
7/29/86 
7/28/86 

8/3/86 

8/1/86 
7/21/86 
7/21/86 


8/6/86 
8/6/86 


8/6/86 
8/6/86 
8/6/86 
8/6/86 
8/6/86 


8/4/86 
7/28/86 
7/25/86 

8/4/86 
7/25/86 


:MacApp 1.0B2 (3):MacApp Samples:Conference Sample: 


AppleTalk.rsre 22322-2222 6K 
Conference .make TEXT MPS 2K 
Conference.r TEXT MPS TK 
MConference.p TEXT MPS 1K 
UAppleTalk.incl.p TEXT MPS 40K 
UAppleTalk.p TEXT MPS 46K 


UConference.incl.p TEXT MPS 22K 
UConference.p TEXT MPS 10K 


lvbspocid 
lvbspocId 
lvbspoci¢d 
livbspocid 
lvbspociId 
livbspociId 
livbspocid 
lvbspecid 


7/22/86 
7/29/86 
7/30/86 
°7/25/86 
7/25/86 
7/25/86 
7/29/86 
7/29/86 


:MacApp 1.0B2 (3) :MacApp Samples:DemoDialogs Sample: 


DemoDialogs.make TEXT MPS 2K 
DemoDialogs.r TEXT MPS 7K 
MDemoDialogs.p TEXT MPS 1K 
UDemoDialogs.incl.p TEXT MPS 9K 
UDemoDialogs.p TEXT MPS 3K 


lvbspocīId 
lvbspocīId 
lvbspocId 
lvbspocīd 
lvbspocīId 


7/18/86 
7/30/86 
7/30/86 
7/25/86 
7/25/86 


:MacApp 1.0B2 (3):MacApp Samples: DemoText Sample: 


DemoText .make TEXT MPS 2K 
DemoText.r TEXT MPS 8K 
MDemoText .p TEXT MPS 1K 
UDemoText.incl.p TEXT MPS 13K 
UDemoText.p TEXT MPS 5K 
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lvbspoclid 
lvbspoclid 
livbspociad 
lvbspocId 
ivbspocid 


7/24/86 
71/28/86 
7/25/86 
8/1/86 
8/1/86 


August 6, 1986 


PM 


PM 


7/28/86 


7/3/86 
7/3/86 
71/3/88 
7/3/86 
7/3/86 
7/3/86 
7/3/86 
7/3/86 
7/3/86 
10/31/85 
2/7/85 
7/3/86 
7/3/86 


7/28/86 
7/28/86 


6/12/86 
6/16/86 
6/16/86 
6/16/86 
6/16/86 


6/27/86 
5/20/86 
3/6/86 
3/6/86 
3/6/86 


5/14/86 
6/27/86 
5/20/86 
7/8/85 
7/8/85 
7/8/85 
10/31/85 
7/8/85 


6/27/86 
5/20/86 
7/8/85 
10/31/85 
7/8/85 


6/27/86 
5/20/86 
7/8/85 
10/31/85 
7/8/85 


PM 
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MacApp Release Disks (version 1.0B2) 


:MacApp 1.0B2 (3}):MacApp Samples:DrawShapes Sample: 


DrawShapes.make TEXT MPS 2K lvbspocId 7/24/86 
DrawShapes.r TEXT MPS 6K lvbspocId 7/30/86 
MDrawShapes.p TEXT MPS 1K lvbspocId 7/25/86 
UDrawShapes.incl.p TEXT MPS 45K lvbspocid 8/5/86 
UDrawShapes.p TEXT MPS 18K lvbspocId 7/25/86 


tMacApp 1.082 (3):Still More MacApp Source Files: 
UWritelnWindow,incl... TEXT MPS 20K lvbspocId 7/30/86 
UWritelnWindow.p TEXT MPS 4K lvbspocid 7/3/86 


AM 


6/27/86 
5/20/86 
12/19/84 
6/5/86 
2/6/85 


7/3/86 
71/3/86 


ee eee ee eee eee eee eee ———— ee Re Re ee ee ee ee e i me 


:MacApp 1.0B2 (4): 
More MacApp Samples Folder 196K lvbspocid 8/6/86 


:MacApp 1.0B2 (4):More MacApp Samples: 


Flow Sample Folder 45K lvbspocid 8/6/86 
Nothing Sample Folder 15K lvbspocId 8/6/86 
OneBox Sample Folder 29K lvbspocid 8/6/86 
Puzzle Sample Folder 49K lvbspocId 8/6/86 
SmallEditor Sample Folder 16K lvbspoclId 8/6/86 
TwoDocKinds Sample Folder 42K lvbspocid 8/6/86 


:MacApp 1.0B2 (4):More MacApp Samples:Flow Sample: 


Flow.make TEXT MPS 2K ivbspocId 7/29/86 
Flow.r TEXT MPS 5K IvbspociId 7/30/86 
FlowExtras.rsrc 1K lvbspocId 6/2/86 
MFlow.p TEXT MPS 1K ivpspocId 7/25/86 
UFlow.,incl.p > TEXT MPS 14K lvbspocId 7/29/86 
UFlow.p TEXT MPS 3K lvbspociId 7/25/86 
UFlowchart.incl.p TEXT MPS 16K lvbspocId 7/25/86 
UFlowchart.p TEXT MPS 4K ivbspocid 7/25/86 


iMacApp 1.0B2 (4):More MacApp Samples:Nothing Sample: 


MNothing.p TEXT MPS 2K lvbspocId 7/25/86 
Nothing.make TEXT MPS 2K lvbspocId 7/18/86 
Nething.r TEXT MPS 5K lvbspocId 7/30/86 
UNothing.incl.p TEXT MPS 3K lvbspocid 8/4/86 
UNothing.p TEXT MPS 4K IlvbspocId 7/25/86 


sMacApp 1.0B2 (4) :More MacApp Samples:OneBox Sample: 


MOneBox.p TEXT MPS 1K lvbspocId 7/25/86 
OneBox.make TEXT MPS 2K lvbspocId 7/18/86 
OneBox.r TEXT MPS SK lvbspocId 7/30/86 
UOneBox.incl.p TEXT MPS 14K lvbspocId 7/25/86 
UOneBox.p TEXT MPS 8K lvbspocId 7/25/86 


:MacApp 1.0B2 (4):More MacApp Samples:Puzzle Sample: 


MPuzzle.p TEXT MPS 1K lvbspocId 7/25/86 
Puzzle.make TEXT MPS 2K lvbspocId 7/18/86 
Puzzle.r TEXT MPS 6K lvbspocId 7/30/86 
UPuzzle.incl.p TEXT MPS 27K lvbspocId 7/29/86 
UPuzzle.p TEXT MPS 14K lvbspocId 7/29/86 


sMacApp 1.0B2 (4):More MacApp Samples:SmallEditor Sample: 


MSmallEditor.p TEXT MPS 2K lvbspocid 7/25/86 
SmallEditor.make TEXT MPS 2K lvbspocId 7/18/86 
SmallEditor.r TEXT MPS 5K lvbspocId 7/30/86 
USmallEditor.incl.p TEXT MPS 5K lvbspocId 7/25/86 
USmallEditor.p TEXT MPS 3K lvbspocId 7/25/86 


August 6, 1986 


PM 


7/28/86 


6/2/86 
6/16/86 
6/16/86 
6/16/86 
6/16/86 
6/16/86 


6/26/86 
5/20/86 
5/23/86 
7/10/85 
7/10/85 
7/10/85 

2/4/86 
7/10/85 


3/6/86 
6/27/86 
5/20/86 

3/6/86 

3/6/86 


3/4/86 
6/27/86 
5/14/86 

3/4/86 

3/4/86 


7/8/85 
6/27/86 
5/19/86 

10/31/85 

2/8/85 


7/10/85 
6/27/86 
3/20/86 
7/10/85 
7/10/85 


6:16 


A PDP DP PDP PHP UI 
a pw Oo 
mo wo wo 


nr 


iw un tI 


5232 
4:49 
9:14 
5:41 
5:39 


PM 
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:MacApp 1.0B2 (4) :More MacApp Samples :TwoDocKinds Sample: 


MTwoDocKinds.p TEXT MPS 
TwoDocKinds .make TEXT MPS 
TwoDocKinds.r TEXT MPS 
UTwoDecKinds.incl.p TEXT MPS 
UTwoDocKinds.p TEXT MPS 
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2K lvbspocId 7/25/86 
2K lvbspocId 7/18/86 
6K lvpspocid 7/30/86 
21K lvbspocIad 7/28/86 
12K lvbspocid 7/25/86 


August 6, 1986 


PM 
PM 
PM 
PM 
PM 


3/4/86 
6/27/86 
5/20/86 
3/4/86 
3/4/86 


An oOo Pf N 


200 
2:51 
314 
$35 
>33 


AM 
PM 
AM 
AM 
AM 
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Converting a Lisa Workshop MacApp Program to MPW 


To bring your Lisa Workshop version of your application files over to the MPW world follow 
these steps (NOTE: This only discusses changes related to building an application. A separate 
memo describes programming changes needed to update your program from release 1.0A40 or 


earlier): 


You should follow the steps in setting up for MacApp outlined in the “MacApp 


1.0B2 Release” document. 


In the Lisa Workshop, copy your source files onto a Macintosh disk using 
Maccom: 


rMaccom<cr> {run maccom } 

scy<cr><cr> {tells maccom to convert text files} 
f<cr>MPS <cr><cr><cr> {sets the type and creator fields} 

q {quit settings sub-options} 
LYourApp=.text, $<cr> {copy all sources from Lisa to Mac} 
eq {eject disk, quit maccom} 


On the Macintosh, place your files in a folder inside the MacApp folder named 


YourApp Folder. Rename your files to use the following naming conventions: 


from to 

YourApp.m.text MYourApp.p 
Main program} 

YourApp.u.text UYourApp.p 


{The interface part of your application unit} 


YourApp.u2.text UYourApp.inc1.p 
{The include file that contains the 
implementation of the unit} 


Delete the {$U filename} info from the USES statements of MYourApp.p 
and UYourApp.p. Add UList to the USES list. The USES list should now 


look similar to this: 


USES 
MemTypes, QuickDraw, OSIntf, Toolintf, Packintf, 
UObject, 
UList, 
UMacApp, 
UPrinting, 


UYourApp; 


ac bkd 


(The Pascal compiler automatically appends a “.p” to the unit name and searches 


for files by that name) 


Change the include statement at the end of UYourApp.p from 
{$I YourApp.u2)} to {$I UYourApp.incl.p). 


Correct any spelling errors which may occur because of the longer identifiers in 


MPW. The MPW tool Canon is very useful for this. You won’t catch all of 


these until you try to compile the first time. 
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7. Using your existing Application resource file (presumably built on a previous 
version on the Lisa Workshop) as the source, go into ResEdit and copy and 
paste all of the resources unique to your application into a new file called 
YourAppExtras.rsrc. Typically this may include some of the following resource 
types: ALRT, BNDL, DITL, FREF, ICN#, PICT, SIZE, WIND. Copy all of 
the MENU resources, except for the Debug menu. Do do not copy any CODE 
or MNTB resources. If you had application alerts numbered below 1000, there 
may be some new MacApp alerts that collide with yours. You will have to 
renumber yours (and make the corresponding change in your source files). 
(Note that ALRT number 201 is the “About...” alert and should be copied) 


At this point you need to make some decisions (that you can change later) about 
the future editability of each resource. Examine the file to see which resources 
you would prefer to edit as a Rez template and which resources you would 
-tather modify in ResEdit. You should now run DeRez to create a Rez file, using 
the skip option to skip the resources that you have determined you want to keep 
as ResEditable resources. However, you must not skip the MENU resorces. 
They need to be DeRezed and converted to cmnu resources. (Since MacApp can 
associate a command number with any menu item, we use a special menu 
template with resource type cmnu. The cmnu template, which is defined in the 
file MacApp.r, is exactly the same as a MENU template with the addition of an 
integer command number field for each menu item. When you build an 
application, the Make file runs a program called PostRez immediately after Rez 
which converts the cmnu resources back into MENU resources, and places the 
command number information into an mntb resource for use by MacApp.) 


The DeRez statement will look something like: 


derez YourAppExtras.rsrc ð 
-skip ALRT ð 

-skip BNDL ð 

-skip DITL ð 

-skip FREF ð 

-skip "ICN#' ð 

-skip PICT ð 

-skip SIZE ð 

-skip WIND ð 
"{Rincludes}Types.r” >YourApp.r 


If there are some resources of a particular type that you want some of in 
ResEditable format and others in Rez format, you will have to DeRez all of them 
and delete from the Rez file those templates that you want in ResEdit format. 
Any resource that you choose to keep as a Rez template must be deleted from 
YourAppExtras.rsrc. 


8. Open YourApp.r and add the following lines at the beginning of the file 
(depending on the needs of your application): 


#ifdef Debugging 

include MacAppRFiles"Debug.rsrce"; 
endif 

include MacAppRFiles"MacApp.rsrc"; 
include MacAppRFiles"Printing.rsre"; 
include MacAppRFiles"Dialog.rsre"; 
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If you kept any resources in YourAppExtras.rsrc in Step 6, add the following line 
to YourApp.r: 


include “YourAppExtras.rsrce"; 


You also need to add the following line (it includes the CODE resources that the 
Linker will create during the build process): 


include “YourApp"™ 'CODE'; 


9. Next, you need to edit the MENU templates in YourApp.r. Any menu that 
contains menu items that have a command number equivalent must be converted 
to a cmnu template. To do this, simply change 'MENU' to 'cmnu' in the 
template header. For each menu item add the command number as the last field. 
If there is no command number for a particular item, type “nocommand”. Be 
sure to use the new command numbers for MacApp commands. See the sample 
.T files for guidance. 


10. If you have performed the programming changes necessary to bring your 
application forward to the current MacApp release (described in a seperate 
memo), then you are ready to build your application. The build process is 
described in the MacApp Reference Manual. 
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MacApp Change History 
Changes from Release 1.0B1 to Release 1.0B2 


UObject 

Changed the method TObject.ClassName to TObject. TypeName. 

= There is a new debugger flag (type 'XF' in the debugger) that affects calls to FailOSErr, FailMemEnor, and 
FailResError. When this flag is TRUE, any call to these procedures will cause the debugger to pause and ask you to 
enter the desired error code. You can use this feature to test your error handling code. (Note that this does not test 
whether or not you have checked for all possible error conditions; it just checks that you recover properly from the errors 
you do test for.) 

“© We added utility procedures: WrLbiPt, WrLbiPtr, WrLbiRect, and WrLblBoolean, which take an appropriate value 
and a string label, and prints out the value with a label. This is especially useful in Inspect methods. 

UList 


TList Each has a Failure handler to adjust the fEachCount field. This will allow the Each call to properly recover from 
Failures in the procedure it applies to each element. 


The type-checking code in UList was disabled in 1.0B1. It is now enabled again. 

ss TList.Each cannot recover properly if you terminate the Each with a non-local Exit. (For example, if procedure A 
calls Each and passes it procedure B, then if B does an Exit(A) the Each call will be terminated without getting a chance 
to clean up.) You should avoid terminating the Each call with a non-local Exit; use the TList method FirstThat instead. 
UMacApp 

General 

= There are more Inspect methods implemented. Use the I command in the debugger. 

“= Added the global procedure SetCmdName and SetCmdilcon to set a menu command name or icon. (For convenience, 
they accept a command number parameter.) You should call these procedures (as well as SetStyle) instead of making 
direct Toolbox calls. Your menus will not function properly if you call the Menu Manager directly within a 
DoSetupMenus method and the menu you are changing is one that MacApp handles (menu id 2 through 63). This is 
because of some optimizations we did to the menu setup code. 


ve Fixed bugs related to freeing of controls when a window was freed. This solves problems with garbage left on the 
heap and with crashes due to a corrupt heap. 


Added additional error checks in various places. 


All trap patches set up the value of A5 before executing. This is a requirement for being compatible with future software 
architectures, 


MacApp does not install its segment loader patch if the application is running on a machine with 128K ROMs. 


Fixed bug in RectlsVisible while printing. 
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Removed the succeeded parameters from various methods relating to closing documents and windows. We now use the 
Failure mechanism instead. If the user cancels closing a document we signal Failure with an error of noErr. 


Added global procedures for dealing with files. CloseFile, DeleteFile, FillinDirID, OpenFile, and TempName. 
The debug window adjusts its size to the size of the screen. 

TEvtHandler 

Moved the field TEvtHandler.fFreeOnClosing to TWindow, which is the only object type that really used it. 


TEvtHandier Free now manages gTarget as follows: IF SELF = gTarget THEN gTarget := fNextHandler, This fixed 
problems where gTarget would be incorrectly set to gApplication. 


Moved methods TEvtHandler.DoRead and .DoWrite to TDocument. 

TEvtHandler.InstallSelection has new parameters (wasActive, beActive: BOOLEAN), 

TApplication 

TApplication.SFPutParms has an additional parameter, which is the default name to use in the StdPutFile dialog. The 
default implementation does not change the parameter. (When MacApp calls this it passes in the current document 
name.) j 

Folded the code from TApplication. Terminate into TApplication.Close. 

Fixed bug in TApplication.TrackCursor in which the cursor would not be changed to an arrow correctly. 

TDocument 

se TDocument supports disk-based documents. The cail to [Document has 2 extra parameters, keepDataOpen and 
keepRsrcOpen. These indicate whether or not MacApp should leave the file fork(s) open after reading the file. (Note that 


keeping the resource fork open is not recommended because of problems managing the resource maps.) 


There are other new fields of TDocument that affect reading/writing documents (eg., fDataOpen, fRsrcOpen, 
fDataPerm, fRsrcPerm, fDataRefnum, fRsrcRefnum, fSavelnPlace). 


a The entire mechanism for saving documents has changed; look at the code for TDocument Save (to start) if you are ; 
interested. Some methods you may want to look at are FreeFile, SavedOn, and GetTempName. 


sx TDocument.DoRead has an extra parameter rsrcExists, which replaces the field fRsrcExists of TDocument. 


se DoWrite has an extra parameter makingCopy, which indicates if this is a Save a Copy In command. (Disk-based 
documents might use this parameter to optimize their saving code, by coordinating the in-memory structures with the 
on-disk structures if it is FALSE.) 


sx Fixed the bug where if you close an Untitled window, answered OK to save the changes, but Cancel the Standard 
File dialog, the document would be closed and all changes lost. (This is now handled by the Failure mechanism; if you 
do this you will see messages in the Debug Window which are supposed to appear.) , 


TFrame/TWindow/T View 


ex Added global procedures AdaptToScreen, SimpleStagger, and ForceWindowOnScreen. The first two can be used 
(they are completely optional) if you do not save the window size and position in your document or if you open a new 
document. AdaptToScreen will adjust the size of the window to take into account the size of the screen; it assumes that 
the window template is specified for the standard Macintosh screen size. SimpleStagger can be used to stagger windows. 
You pass it a TWindow object, dh, and dv values, and a counter. (The counter is a global variable that you must declare; 
SimpleStagger maintains it for you.) Force WindowOnScreen should be used if you restore the window size and position { 
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from the document. It adjusts the window to ensure that it is on the screen. (For example, if you saved the document on 
a Mac XL, with its larger screen, then open it on a Mac.) 


se Added global procedure GetWindowPos. This may be useful in getting the current position of a window, if you 
wanted to save it in the document. 


se Added field TFrame.fSBarOffset. This is used to adjust the scroll bar positions; this Rect is added to fContentRect, 
and the scroll bars are made flush against the result. MacApp uses this to support windows with a grow box and only 
one scroll bar. You might want to set this field to artificially shorten a scroll bar (as in the MPW Shell). 

Moved the method TFrame.Activate to TWindow, and replaced it with TFrame.ActivateContents. 

sx Changed the parameters to TView.Activate to wasActive, beActive: BOOLEAN. TView.Activate is called for every 
activate event, even if MacApp thinks the window is active. If you override this, you should check to see if wasActive 
<> beActive (if you care about this). 

TFrame.HaveView calls InstallSelection twice; to de-install the old view and install the new view. 

=æ TWindow.I Window now sets fContentRect to (0,0)/(0,0) instead of the size of the Window Manager window. This 
field is adjusted in TWindow.Open with a call to TWindow.Resize. This was done so that you can easily adjust the size 
of the window with a call to the Window Manager before the window is opened. 

This may affect your application if you are looking at the window’s fContentRect field to determine (for example) 
the size of frames. Instead, you should assume that TWindow.ChangedSize will be called to resize the frames 
appropriately. If you do not override TWindow.ChangedSize, you should be careful about calling IFrame with 
wantHResizing or wantVResizing FALSE. These should be TRUE if the frame’s right or bottom edge is next to the 
edge of the window, even if you do not allow the window to change its size. 


= TWindow.Activate always calls InstallSelection, even if MacApp thinks the window is already active. This fixes a 
bug in which the highlighting in modeless dialogs would be lost. 


Fixed a bug in which a view with a sizeDeterminer of sizeFrame in the horizontal (vertical) direction would not be 
resized properly if installed in a frame whose top (left) edge was not 0. 


TView.BeinFrame calls FrameChangedSize, in case it needs to alter its extent. 


UPrinting 


= Merged UXPrinting into UPrinting. You should change any declarations of TXPrintHandlers to TStdPrintHandlers 
and call InitPrinting instead of InitXPrinting at initialization. 


Removed support for background printing, because it causes memory management problems. 
Removed the code that did scaling while printing, because the printing architecture did not really require it. 


sx Fixed a bug in TStdPrintHandlerFree which would free the print information twice when a document was closed 
(thereby trashing the heap). 


æ Fixed a bug whereby you could not cancel printing. 


æ MacApp does not keep the Print Manager open all the time. This fixes bugs with running several MacApp 
applications under Switcher and other problems related to printer resource files. 


e Removed the starting page number and page margins dialogs. It is easy to do them yourself, if you want. 
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UDialog 


sx Removed the succeeded parameter to TDialogView.IDialogView. This also sets fDisposeOnFree to TRUE iff 
itsStorage = NIL. Before you had to explicitly set it to TRUE. 


ss Changed the parameters to TCatView.Activate to wasActive, beActive: BOOLEAN. 

=æ Change TDialogView.Free so that it correctly disposes of the item list. This solves problems With leaving garbage 
on the heap when a dialog was closed. , 

UTEView 

Added field fFontInfo which contains font metrics for the font in the view. 


Added methods DoMakeEditCommand and DoMakeTypingCommand to support customization of the standard command 
object types. 


Added method DoneTyping to signal the end of a typing command. 
se TEView now handles the clear key and Clear menu item. 
TEView does not use the Window Manager port while printing; it creates its own port. 


TTEView.StuffTERects checks for setting too small a rectangle. This solves a problem where TextEdit would loop if 
the rectangle is too small. 


sx Fixed a bug in which the fText field might be freed twice (once by TextEdit and once by the application). The 
application is now responsible for freeing this handle. 

UTrace/UWriteln Window 

æ Fixed bug where tracing through a call to TObject.Free (among others) would crash the debugger. 

Object type names now print 8 characters instead of 7. 


sr Fixed bug in the WritelnWindow where doing a RESET of a disk file would start reading from the WritelnWindow 
instead of the disk. 


MacApp flushes the volume when you close the output redirect file. 
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Changes from Release 1.0A40 to Release 1.0B1 


Spelling 

MPW supports 63 significant characters in all identifiers. MacApp, the building blocks, and all the sample programs 
were edited to correct spelling errors which occured after the first eight characters. The MPW utility Canon is helpful for 
correcting errors of this kind. 

USES Syntax 


All USES statements were changed to reflect the new MacApp file naming conventions. The $U compiler directives 
were removed since MPW Pascal will search a list of directories to locate interface files. 


Build Files 


The build files are completely different for MPW and make use of the MPW utility Make. See the document, 
“Converting a Lisa Workshop MacApp Program to MPW.” 


Resource Files 


MPW uses Rez instead of RMaker. Rez has a completely different syntax from RMaker. To convert your resources, see 
the document, “Converting a Lisa Workshop MacApp Program to MPW.” 


Sample Programs 
Several bugs were fixed in DrawShapes. 


OneBox (and by extension, TwoDocKinds) was fixed to print correctly on the Laser Writer. 


Changes from Release 1.0A39 to Release 1.0440 


Menus 


MacApp now will insert the name of the command in the Undo menu item. It gets this string from the command 
number stored in the command object. If you have command objects that correspond to operations not invoked from a 
menu (i.e., with the mouse), then you should include a buzzword menu in your resource file from which MacApp can ger 
the command name. See the sample programs for an example of this. 


We have changed the way in which the menu bar is initialized. Previously, MacApp read in menus starting with ID 1 
until there was a break in the sequence. Now MacApp uses the menu bar feature of the Toolbox. 


MacApp will look for an MBAR resource with ID 128 when it starts up. This resource indicates the IDs of the menus 
that should be read in and displayed initially. 


MacApp also looks for the MBAR/129 resource, which specifies menus that are read in but not displayed immediately. 
(These would be menus that are dynamically added to/removed from the menu bar by your application.) 


Menus that are not listed in either MBAR resource are not read in by MacApp. For example, the buzzword menus do not 
need to be in either resource, since they are never installed in the menu bar. (MacApp special cases the debug menu, 
which has ID 900, and reads it in if debugging code is on. This menu must not be listed in either MBAR resource.) 

If the user types a key while the command key is held down, MacApp now calls the method 
TApplication.CommandKey. This can be used to implement command keys that do not appear in the menu. 
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You can also use this method to implement automatic repeat of certain command keys. If the global flag 
gRepeatCmdKeys is TRUE, MacApp will allow auto repeat of all command keys. If you want selective repeating, you 
can override TApplication.CommandKey and set the AutoKey flag of the info record to FALSE. 


We have refined the handling of menus a bit. MacApp will only manage menus with IDs from 1 to mLastMenu (=63). 
You have to manage other menus (i.e., enable, disable). If you have non-standard (i.e., graphical) menus, their IDs 
should be over mLastMennu, so that they are not passed to the Menu Manager by MacApp. 


+ 


You should not use programmatically created menus; i.£., your resource file should contain at least the menu title. 


Error Handling 


MacApp handles a few more error conditions than before. In addition, the new sample programs (all except Flow) try to 
handle errors correctly. 


MacApp now handles errors at initialization time. Initialization time is defined as the period between the calls to 
InitToolbox and TApplication.Run. If a Failure is called during this period, it will eventually filter up to the procedure 
InitFailed. This will display an alert and exit to the Finder. 


MacApp also displays alerts automatically if a Failure is propagated up to the main event loop. The topmost error 
handler will call TApplication.ShowError if the error is <> noErr. It passes the error code and message value to 
ShowError. By default, ShowEnror calls the global procedure ErrorAlert. 


You should look at the implementation of ErrorAlert to see all the detail about what it does. This memo just describes 
the mechanism from the programmer’s point of view. 


The error code is looked up in 2 resource tables. (The lookup routine is called LookupErrMessage. Refer to this as well 
as the file MacApp.R.TEXT to see the format of the tables), One supplies a reason string (e.g., “the disk is locked”) and 
the other a recovery string (e.g., “Eject the disk and move the tab.”), The recovery string may be-empty if the reason is 
sufficiently clear. 


The message value is used to derive an operation string, which describes what was happening at the time of the error 


(e.g., “save the file”). All 3 strings are plugged into an alert to read “Could not save the file because the disk is locked. 
Eject the disk and move the tab.” 


There are certain conventions you should follow. If you want to put up your own alert, your error handler should check 
that error <> noErr, put up the alert, and call Failure with an error of noErr. The convention here is that a Failure with | 
error = noEsr means an error happened, but it has already been reported to the user. 


If an error handler does not want to supply a message value, it should pass 0. If it does want to supply a value, it should 
do so only if the current message is 0. We have provided a utility procedure FailNewMessage to do this. 
FailNewMessage takes the error and message values, as well as a new message value you would like to supply. It calls 
Failure and passes the appropriate message value. 


MacApp supports several classes of messages: 

If the message is msgCmdErr + <some command number> then the operation string will be derived from the name of 
the corresponding command number (e.g., “Could not complete the “Revert” command because ...”). MacApp actually 
uses this kind of message in TApplication.MenuEvent. 


If the message is msgAlert + <some alert number> then MacApp just displays the requested alert without any 
parameters. 


If the message is msgLookup + <some INTEGER> then MacApp looks the INTEGER up in another table to find the 
operation string. 
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Otherwise the 4 byte message is divided into 2 INTEGERs. The high-order INTEGER specifies the resource ID of a 
STR# resource and the low-order INTEGER the index within that resource. This form of message is also used by 
MacApp. 


Views and Frames 


The TPad class has been removed. The coordinate transformations are now done by global procedures and RECORD 
types. As a result, the type VRect is gone, and TView.InvalVRect is now TView.InvalidRect. 


Printing 


The call to InitPrinting no longer takes a parameter as to whether to keep the Print Manager open all the time. For this 
release, the Print Manager is open all the time. In the next release, we will change this to open the Print Manager only 
as needed. This future change may affect your program if it uses resource files. Since the Print Manager opens resource 
files, you might find that the current resource file changes; the solution is to ensure that your intended resource file is the 
current one before trying to access it. 


UpPrinting was divided into UPrinting and UXPrinting. XPrinting contains the TXPrintHandler class. The idea was to 
put the basic printing code in UPrinting and more sophisticated code in UXPninting. Refer to the sample programs 
OneBox, DemoText, and DrawShapes for examples of using XPrinting. 


Unfortunately, after the division was made, we changed our mind about this, and plan on merging the two units again. 
This will happen with the 1.0B2 release. The only effect on your applications is that if you create a TXPrintHandler in 
release 1.0A40 you will have to create a TStdPrintHandler in release 1.0B2. 


Windows ; 
We have removed all the code and data which tried to position new windows on the screen. Now any window that you 
open will appear exactly at the position specified in your window template. 


If you want to resize or move your window when it is opened, you should call the appropriate Window Manager routines 
(SizeWindow and MoveWindow). The appropriate place to do this is in your implementation of 
TDocument.DoMakeWindows. After creating your TWindow object, you can call the Window Manager to position the 
window. Since the window is invisible at this ume, the changes will not cause any flashing on the screen. 


In the next version of MacApp, we will have a couple of utility routines that will stagger windows. Most applications 
will want to call these routines so that windows do not obscure one another, or use these routines as a guide to more 
complicated routines. 


MacApp no longer limits the number of windows your application can open. The parameter that specified this in 
InitToolbox has been removed. In the normal case, window storage is allocated as non relocatable blocks in the heap. 
Since code segments are pushed to the top of memory, the bottom of memory is free to be used for window records and 
master pointer blocks. 


We have not solved all the memory management problem yet, however, so if you open a great number of windows and 
use so many handles that the system creates a new master pointer block, you may encounter some heap fragmentation. 


We added a method TWindow.SetTitleForDoc, which is called when the document’s name changes. The intent is that 
each window will change its tile to incorporate the new document name. 


MacApp supports the new zoom box that is available on machines with new ROMs. To use this feature simply use a 


window type code of 8 in your resource file. If your application runs on a machine with new ROMs your windows will 
have the zoom box. We still support double clicking in the title bar, but this may be removed in a future release, 
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Commands 
We removed the global gDidLastCommand and replaced it by a field of TCommand called f{CmdDone. 


MacApp constructs a negative command number if the selected menu item did not already have one. This formula is 
cmdNumber = - (256*menuNumber + itemNumber). MacApp now checks to ensure that the menuNumber is <= 127 
and itemNumber <= 255, and will display a debugging message if this is not true. ; 
MacApp now support another kind of derived command number. If the item number retumed from the Menu Manager is 
negative, MacApp simply negates the item number and returns that as the command number. This allows for graphical 
menus that could have more than 255 items in them. 


The command number assignments have changed. You will have to change your application to reflect this. See the 
sample program resource files for the correct new command numbers. 


Documents 


MacApp supports a range of command numbers for Open and New commands. This might be useful if your application 
supports multiple document types. Your applications should enable these commands if you use them. You do not need 
to handle the commands, however, MacApp takes care of that automatically. Refer to the TwoDocKinds sample program 


We added support for read/write of the resource fork of documents. In TDocument.IDocument you indicate whether your 
document uses the resource and/or data fork(s) of the file. If you use the resource fork, when DoRead or DoWrite is 
called the topmost resource map will be that of your document. When reading, you should check the field fRsrcExists to 
see if the document being read has a resource fork. 


TApplication.1A pplication no longer takes the application signature. Instead, TDocument.IDocument takes a parameter 
to specify the creator of the document. This allows you to create documents belonging to other applications, e.g. 
MacWrite. 


Lists 


There is a new unit called UList, which contains a TList class, TList implements a list of objects, is used in various 
places in MacApp, and is available for use in your own programs. 


Debugger 


There is a new Inspect command in the debugger. This calls the Inspect method of the object you specify. The Inspect 
method should first call INHERITED Inspect and then writeln any information, specific to that object type, that you 
might want to see. Right now, we haven't implemented very many Inspect methods, but we plan on adding more with 
the next release. 


You can now refer to certain global objects by name. These include gTarget, gDocList, gFreeWindowList, gClipView, 
gClipUndo View, gDocument, gLastCommand, and gApplication. Symbolic names apply to the Inspect and Fields 
commands in the debugger. 


Instead of typing a number in those commands, type the name of a symbol or ‘symbol if the name begins with a hex 
digit. The symbol name will be passed to the method gTarget.LookupS ymbol (which you can implement in your 
TApplication, TDocument, etc. object types). If the symbol cannot be found there, then the debugger looks in a static 
table that it maintains. Refer to UTrace for more details on the symbols. 


The W command was changed to a 2 character command. WF brings the debug window to the front. WB sends it to the 
back. WR lets you resize the window with the mouse. 


If you do an ES command in Macsbug, MacApp now correctly cleans up before returning to the Finder. 
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The debugger flags (debugger X command) have changed slightly. If M is true, the debugger will report changes in the 
number of master pointers at procedure entry and exit. If S is true, it reports segments that are loaded. If B is true, then 
either of these events will cause a break into the debugger. 


Fixed a problem in which quitting the application normally would not deinstall the debugger properly. This would often 
manifest itself by not being able to enter Macsbug when continuing after an error. 


Dim Highlighting 


MacApp now supports dim highlighting. It is possible to have you selection dimly highlighted when the window is 
deactivated. The most common way of doing this is to XOR a gray pattem for dim highlighting instead of the normal 
black pattern. 


You should rename your old HighlightSelection methods to be DoHighlightSelection. This new method is called with 
the current and desired highlight states (fromHL and toHL). A highlight state is an integer which will be one of the 
constants hlOff, hIDim, or hlOn. When your method is called MacApp ensures that fromHL <> toHL; if you call 
DoHighlightSelection, you should make sure of the same thing. 


If your view highlights by XORing a black pattern, then you can implement dim highlighting by calling SetHLPenState 
with the parameters passed to DoHighlightSelection. This will set up the pen so that you can do a FrameRect, 
PaintRect, etc. and get the proper highlighting. 


There are also constants such as h1DimOn which can be used to test for particular highlight transitions without regard as 
to which is hlFrom and which is hiTo. Just compare the value hlFrom+hlTo to these constants. 


For compatibility with past releases (or for text views, in which XOR dim highlighting doesn’t work well), it is 
possible to tell MacApp not to use dim highlighting. TView.IView has a new parameter, which indicates the highlight 
State (hiDim, etc.) to use when the window is inactive. If you pass hlOff for this, then the highlight behavior wil! be 
the same as before. To take advantage of dim highlighting, you should pass hlDim as this parameter, 


Miscellaneous 


You can test the global flags gROM128K and gHFSInstalled to see if the new 128K ROM and/or the HFS is installed 
on the current machine. 


We reorganized the alert numbering to assign ranges to each unit. This should not affect your resource files too much if 
you use the .RSRC include files for MacApp’s resources. 


0 to 249 UMacApp 

250 to 299 UPrinting & UXPrinting (these will be merged) 
300 to 349 UDialog 

350 w 399 UTEView 

400 to 449 UAppleTalk 

460 to 999 {reserved for future use} 


1000 and up {available for applications} 
Added global gMainEventMask, which is the event mask to use in the main event loop. 
Added TApplication.DiskEvent to handle disk inserted events. 


We changed some of the custom MacApp resource types to all lowercase letters, because these types are reserved by 
Apple. 
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TEView 


Cut, Copy, and Paste operations can be undone. Undo of typing has bugs, but you can experiment with it if you 
turn on the experimenting flag in the debugger. 


Dialogs . 
TDialogView.DoltemSelected and TDialogltem.ItemSelected can now return objects of type TCommand; as a result, 
modeless dialogs can initiate MacApp-style commands. 


Bringing Your 1.0A39 Sources Forward 


Here is a quick summary of major things to look out for when converting your existing application from 1.0A39 to 
1.0A40: 


1. Main Program. InitToolbox no longer has the number-of-windows parameter. InitPrinting no longer 
has the keep-open parameter. TApplication.[Application no longer has a document creator signature 
parameter. gSignature is gone. 


2. Documents. TDocument.IDocument now takes both the creator and type signatures of the document. 


3. New Unit. The unit UList is new. Make sure you include it in your USES statement in any of your 
source that also USES UMacApp. It must come before MacApp in the USES list; look at the sample 
programs for an example. 


4. RMaker Files. Rip out all the common resources, and replace them by include directives (see the 
sample programs for examples). Update your command numbers. Make sure you have any common 
resources (like the Clipboard Window and new MBAR resources) which don’t appear in the include files. 
Make sure your STR# 255 resource is up to date (again, look at the samples). 
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Changes from Release 0.3 to Release 1.0A39 


Code File Organization 


We have reorganized the MacApp unit, because MacApp.U2. TEXT was becoming very large. In this release, 
MacApp.U2.TEXT contains the classes TEvtHandler, TApplication, and TDocument. All other classes (including, 
TFrame, TWindow, TView, TCommand, etc.) are in a new file called MacApp.U4.TEXT. ‘ 


There is no longer a UFiling unit; its code has been combined into the MacApp unit. 


Debugger 


There is a new debugger flag (A), which defaults to FALSE. If TRUE, then every time you do New(anObject) or 
use TObject.ShallowClone, the debugger will tell you the procedure that is creating the new object, and the class of 
the object. You can then tell the debugger if the allocation should return NIL (i.e., fail). By causing certain 
allocations to fail, you can test your error handling code. (This only applies to object creation now, but we are 
considering extending it to all calls to NewHandle, ...) 


A new debugger flag, M, was added. The function of this flag changed again in the 1.0A40 release: see the 
Debugger section under “Changes for Release 1.0A40,” above. 


There is a new method, TObject.ClassName, which returns the name of the class of the receiver. It is intended for 
use in debugging code only so that you can print out the class of some object. 


Error Handling 


There is a brand new error handling mechanism. (The code is in the UObdject unit, and the assembler file 
Object.A. TEXT.) The basic model is that a routine sets up an exception handler and then runs some code that 
might get an error. Any code that encounters an error can signal a failure and pass back an error code and an 
arbitrary message (a LONGINT). 


You establish an error handler by calling CatchFailures(fi, ErrorHandler ), where fi is declared as a FailInfo and proc 

- is declared as PROCEDURE ErrorHandler(error: INTEGER; message: LONGINT). This call pushes an element on 
an error handler stack, which contains enough information to run the ErrorHandler, if necessary. (Since the fi 
variabie is local to the routine, the memory used by the error handler stack is distributed throughout the program 
stack, and you are only using memory for the error handlers that are currently active.) 


After doing your mainline code, you call Success(fi), where fi is the same variable as in the call to CatchFailures, 
This call pops the top element off theerror handler stack. 


Once an error handler is set up then any other routine can call Failure(error, message) to signal an error. Failure 
pops the top of the error handler stack, restores the stack and important registers to their state at the time of the 
CatchFailures call, and calls the error handler. The call to Failure can be made from a procedure that is any number 
of levels deep in the procedure call stack. There are also utility procedures called FailNIL, which signals Failure if 
its parameter is NIL, and FailOSErr, which signals Failure if its parameter is not noErr, 


The error handler is usually a local procedure, but can also be a global procedure. The calls to CatchFailures and 
Success should be in the same procedure, since if an error is signalled, the state of the machine is restored to that at 
the time of the CatchFailures call, so the procedure that called CatchFailures should still be on the procedure call 
Stack. 


An error handier will generally do some clean up (free allocated objects, close files, etc.) and then itself call Failure 
to propagate the error up another level. At the topmost level, MacApp has an error handler in the main event loop, 
which just branches to the top of the loop. When debugging code is on, then each call to Failure wil! generate a 
message in the debug window telling you the procedure that caught the error (actually, the procedure that called 
CatchFailures initially), the error and the message. (Your error handler can also bypass or retry the operation that 
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failed, The key thing to remember is that a call to Failure pops the top of the error handler stack; if you retry an 
operation, you should call CatchFailures again in order to reset the error handler.) 


In MacApp we have put in some error handlers, but have not finished the job in this release. Specifically, we have 
an error handler in the main event loop, which is the top level handler while the application is running. We have 
also put error handlers in the document read/write code. The sample programs make use of the error handling 
mechanism only for reading, writing, and creating documents. k 


You only need to set up an error handler if one of your routines wants to guarantee that it gets control in case an 
emor occurs. So if you open a file, or allocate some objects that would not get freed some other way, you should 
set up an error handler to take care of these housekeeping details. Look at the DrawShapes and DemoText programs 
to see what they do. 


In general, every time you allocate an object (or a handle) you should check for a NIL return; the same is true of 
calls to the Toolbox that return an error code. 


Document & Window Handling 


We have changed the way in which documents and windows are opened, in order to make things easier to understand. 
The end result is that the simplest applications (those with one window per document and one view per window) are 
slightly harder, but that any other application is substantially easier. 


The basic way in which documents and windows are opened is now: 

The user either asks to create a new document, or open (print) an existing document. . 

-+ If it's an existing document, MacApp finds out its name, volume refnum, and file type. 

e MacApp calls TApplication.KindOfDocument with information passing the command number of the 
request (for operations that started from the Finder we have dummy command numbers), and 
information about the file (or NIL if this is creating a new document); KindOfDocument returns 
another command number (default is the same as the input parameter). s 

e MacApp passes the returned command number to TApplication. DoMakeDocument. As before, this 
function returns a new document of the requested type. The only difference is that the parameter is a 
command number rather than an INTEGER. 

© MacApp then either calls document DolnitialState or document. ReadFromFile, depending on whether 
this is a new document or an existing document. (ReadFromFile used to be called Open.) 

> MacApp then calls document.DoMake Views passing a BOOLEAN indicating if we are printing from 
the Finder or not. DoMake Views is similar to the old DoMakeView (no's’). Instead of returning a 
view object as a function result, DoMake Views is supposed to make all the relevant views for the 
document, and save them in instance variables of the document object. You should use the parameter 
to see if you are printing from the Finder; if so, then you only need to make the view that you want 
to print. 

a If we are Finder printing, then MacApp calls document.Print, which finishes the Finder printing case. 

TDocument.Print gets the view to print from the fDocPrintHandler field. 

If we are not Finder printing, MacApp first calls document. DoMakeWindows. This is a new method 

in this release. DoMake Windows is supposed to take the views that have already been created, and 

create what ever windows are necessary to show those views on the screen. 

e If we are opening an existing document, then MacApp calls document.SetTitle to change the window 
tidled from "Untitled" to the name of the document. 

e Finally, MacApp calls document.Show Windows to make all the appropriate windows visible on the 
screen. 


Now the question is what do you have to do in your application. 
Unless you have more than one kind of document in your application, you do not have to override 


TApplication.KindOfDocument, if you look at the TwoDocKinds program, you will see that it does override 
KindOfDocument. 
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You must override TApplication.DoMakeDocument. If you have only one kind of document, just create a document of that 
type; if you have more than one document type (as in TwoDocKinds), do a CASE statement on the command number and 


create the appropriate type. 


You should override TDocument.DolInitialS tate if there are things that you do to a blank document that you don't want to 
do to a document that will be read from the disk. (For example, in MacPaint, you do not have to erase the document's . 
bitmap if it is going to be read from a file.) ; 


You should override TDocument.DoRead to read the document data into memory. There is no longer a VAR error 
parameter here; signal a Failure (use FailOSErr) if you get an error. 


You must override TDocument.DoMake Views, make all the necessary views, and store them as fields of your document 
object. 


You must override TDocument.DoMake Windows, and make all the necessary windows. To help you do this, we have 
defined two MacApp utilities. 


For simple windows that contain only one view (which may scroll), you can call the function NewSimpleWindow. This 
takes in a resource ID for the window template, a boolean to say if you want a dialog window or a document window, 
booleans to say if you want horizontal and/or vertical scroll bars, and a view. NewSimpleWindow returns a TWindow 
object. The previous versions of MacApp automatically did the same thing as NewSimple Window; now you must 
explicitly call NewSimple Window yourself. 


There is a similar function called NewPaleneWindow. This creates a TWindow object that contains 2 views. A palette 
view (which cannot scroll) at the top or left edge of the window, and a main view (which can scroll). The width (or height) 
of the palete view is fixed. This function is used in the DrawShapes program. 


If you have some other way of arranging your window, then you will have to create the frames, etc. yourself. (This is no 
different that what you would have to do before.) Look at the implementation of NewPaletteWindow to get an idea of how 
to do this. ` 


You normally won't have to override TDocument.SetTitle because MacApp now has the idea of a window title template. 
Within the title template, the string '<<<...>>>' will be replaced by the name of the document each time it changes. If the 
template does not contain that string, it will be constant. This means that you must update your RMaker input files and 
add triple angie brackets to your WIND resources. (For example, replace the string Untitled’ by '<<<Untitled>>>'. Look 
at the sample programs for more details.) 


The tide template is scanned by the TWindow.IWindow method. If the triple angle brackets are found, they are removed. 
(This means that the string between them should be “Untitled” for an English-language application.) The method 
TDocument. SetTitle will substitute the new document name for the variable part of the window title in all the windows 
belonging to the document. 


Instead of remembering the entire original template, MacApp simply remembers (in each TWindow) the first character in 
the variable part of the window's title and the number of constant characters in the title. (These variables are constant 
regardless of the document name.) If for some reason you change the constant part of a window's title, you should update 
these fields or override TDocument.SetTitle. 


You also do not need to override TDocument.ShowWindows in the usual case. The default implementation of this method 
opens all the TWindow objects that belong to the document and have the field fOpentnitially set to TRUE. This field is set 
to TRUE in TWindow.I Window. If you want to prevent a window from being opened at the beginning set the field to 
FALSE after the TWindow object is created. (For example, after you call NewSimple Window or NewPalette Window.) 
There are some changes to code other than the document/window creation code. 


TDocument.DoWrite no longer has a VAR error parameter. As with DoRead, you should signal a Failure if you get an I/O 
error, 
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We also changed the way Revert is handled. Before, we closed the document (which removed its windows from the screen) 
and re-opened it. Having the windows disappear is a little disconcerting to the user. Instead, we now re-read the document 
without first closing it. MacApp handles revert by first confirming the action and then calling TDocument.Revert. 
TDocument Revert calls a new method TDocument.FreeData. You will usually have to override TDocument.FreeData. 
FreeData should free all the storage taken up by the document, and reset the document's fields to a state where the document 
could be read in from disk again. After calling FreeData, MacApp will call document.DolnitialState or (indirectly) 
document DoRead. Look at the Draw sample to see how it implements FreeData; note that it resets fFirstShape and 
fLastShape to NIL so that the document object is in a state where it could be read in from disk. 


(TDocument-Free does not by default call FreeData. In some cases, it might be convenient for your TMyDocument.Free 
method to call FreeData to do some of its work. For example, you might write: “FreeData; <free other non-data stuff>; 
INHERITED Free.” This is done in the Draw program.) 


After calling TDocument.Revert, MacApp calls TDocument.ShowReverted; since the document data has changed, the 
windows must change also. ShowReverted by default calls TView.ShowReverted for every view in every window 
belonging to the document. TView.ShowReverted calls TView.AdjustExtent and invalidates its entire extent. In most 
cases, the default behavior will be adequate. 


In the previous version of MacApp, a document would be closed if its head window’ was closed; otherwise, closing a 
window just made that window invisible. Now the TWindow object has a field called fWouldCloseDoc. If this field is 
TRUE (the default), then closing the window closes the document also. 


There are new methods TApplication.SFGetParms and TApplication.SFPutParms. These methods return several values 
that MacApp sends to the standard file package. For example, if you want to be able to open more than one type of file, 
"you should override SFGetParms to add the extra types to the type list. (See TwoDocKinds for an example of this.) Also, 
if you want to use a custom dialog proc or filter proc you would override these methods. 


Here is a relatively complete list of the changes we needed to make in order to convert TinyEdit from the 0.3 version of 
MacApp to release 1.0A39: 
» Remove the uses statement for UFiling from both TinyEdit U and TinyEdit.M. 
e Change the subclasses of TFileApplication and TFileDocument to subclasses of TApplication and 
TDocument. 
Instead of calling IFileApplication, call IApplication. 
The call to [Document takes a document type string instead of a document ID. 
Change the header of TTinyEd Application. DoMakeDocument to take a CmdNumber as a parameter. 
Rename TTinyEdDocument.DoMakeView to DoMake Views and make ita PROCEDURE. 
Add the method TTinyEdDocument.DoMakeWindows, and call NewSimpleWindow from this method. 
The DoRead and DoWrite methods do not have a VAR error parameter; pass the retum value from the 
file system calls to FailOSEr. 
e Add TTinyEdDocument.FreeData, which sets the text handle size to 0. 
e Adda WIND resource for the clipboard window, alert 217 (used if saving a document fails), and dialog 
261 (used during printing). 
- Changed the WIND resource for the document window (ID 128) so that the title reads 
‘<<<Untitled>>>". 


e o e 9% 2 $ 


Cursors 

We fixed the problem with the cursor flashing in the Note Pad desk accessory. In addition, when MacApp changes the 
cursor from the watch to something else, it now restores the original cursor shape rather than just put up an arrow. (We 
restore the cursor to the last cursor that was passed to the SetCursor call.) 


We also fixed the problem with the spurious mouse up events. 
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Memory Management 


We fixed a couple of bugs having to do with memory not getting freed. Specifically, the scroll bars were not getting freed 
when a window was freed. Also, we noticed that some of the sample programs were not freeing the document's data when 
the document is closed. We have defined a new method TDocument.FreeData, which you should override. (This is 
described in more detail in the section about the new document code.) 


Clipboard Support 


Refer to the MacApp reference manual to find out about this. 


Other Changes to UMacApp 


We have defined a command number for the Save a Copy In... command. This differs from Save As... in that the name of 
the document is not changed by the Save a Copy In... command. 


We fixed the problem having to do with the Save As... command having to delete the old version of the file. MacApp 
would ask about deleting the old copy of the file, but would not delete the correct file. This required a change to 
TDocument.PurgeFiles (it now takes in the filename and volume refnum of the main document file). Also 
TFileDocument. BytesConsumed was changed to TDocumentExtraBlocksConsumed, which retums the allocation blocks 
(not bytes) being used by files other than the main document file and that could be deleted to make more disk space. (If you 
override ExtraBlocks and return a number greater than 0, then you must override PurgeFiles and free up at least that many 
allocation blocks in addition to the main document file. This means that you can simply compress an auxiliary file, rather 
than completely deleting it.) 


You can create a window without a document (it belongs to the application). This is called a FreeWindow in the code. An 
example is the overview window in Combo, or the Clipboard window. 


Added TApplication.ForAllWindowsDo, which performs a specified action for each window on the screen. 


Added OpenWindow and CloseWindow methods. Added TApplication.Open Window and TDocument.OpenWindow, and 
changed old TApplication.Close Window to be CloseWmgrWindow, and added new TApplication.CloseWindow to operate 
on a TWindow object, uniform with the other CloseWindow and OpenWindow methods. Use of these methods facilitates 
handling of windows whose visibility can be controlled both by a menu toggle (e.g. "Show Overview/Hide Overview") as 
well as by the standard close-box in the tide bar and the "Close" item in the File menu. Several examples of their use are 
included in the Combo sample application. 


Added TApplication.AboutToLoseControl. This method is called just before an exit to a world beyond the Application -- 
Opening a Desk Accessory, Switching Out in Switcher, Activating a window of an already-open Desk Accessory, or 
Quitting. The main purpose of this method is to publicize the Clipboard by writing data to the Desk Scrap. 


Added BOOLEAN field TView.finformBeforeDraw and method TView.AboutToDraw. If fInformBeforeDraw is TRUE, then 
the AboutToDraw method is called when the View is about to be told to Draw itself, but BEFORE the Frame it is seen in 
is Focused (this timing allows AboutToDraw do set the View Size, which needs to be done before Focusing). This gives 
the view an opportunity to do things which it needn't do until it actually is seen on the screen. In the case of views seen in 
the Clipboard, it allows views to defer reading in their data from the Desk Scrap until the user actually demands to see the 
Clipboard. 


Print-state (User's latest choices in the Page Setup dialog) is now saved generically with the document, if the document 
chooses. The methods TDocument.DoRead and TDocument.DoWrite read and write the print state; your override of these 
methods should call INHERITED at the point at which you want to read/write the print state. 


Added ToggleSuate, to link the state of a menu item with some BOOLEAN variable; used for example to flip-flop between 


"Show Clipboard" and "Hide Clipboard", and between “Undo" and "Redo". Other examples of its use are found in the 
Combo sample program. 
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UPrinting Changes 

Support for spool-n-pages/print-n-pages added. You can override TStdPrintHandler.ChooseSpoolFile to specify the number 
of pages to print within each subjob (the default is to print all the pages at once). This allows the application to print large 
documents with very little disk space. 


Visible-rect argument added to the Draw-page-feedback methods in views and PrintHandlers, to allow optimizing of 
breaks-drawing code, etc., later. 


Applications can disable user access to the Choose Printer desk accessory by stuffing global variable gChooserOK to value 
FALSE after calling InitToolBox but before calling InitPrinting. MacApp will automatically re-enable the Chooser when 
the application exits. 


Better user feedback during Finder Printing added. 


UTEView Changes 


Í 


Cut, Copy, and Paste commands, with full UNDO, have been added. Typing commands also added but UNDO and REDO 
don't yet work. 

UDialog Changes 

Modeless dialogs are now supported as well as Modal dialogs. 

Command keys are now supported within dialogs. 


Bug fixed in TDialog View. Validate so that it now makes certain all components are valid before signalling success. 


UAppleTalk Changes 


The new global variable "gOK AppleTalk” is set to TRUE if OpenAppleTalk has successfully opened AppleTalk; you can 
interrogate this flag in your code to skip around branches which are only relevant if AppleTalk is actually alive at the user's 
computer. i 


Checking for missed completion flags now only takes place at idleBegin phase of idle, substantially reducing idle load. 


Fixed bug which crashed at termination time if network code was not successfully found at initialization time. 
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